Enum Error 

#[non_exhaustive]
pub enum Error {
    TypeMismatch(Cow<'static, str>),
    BufferOutOfBound(usize, usize, usize),
    EncodeError(Cow<'static, str>),
    InvalidData(Cow<'static, str>),
    InvalidRef(Cow<'static, str>),
    UnknownEnum(Cow<'static, str>),
    TypeError(Cow<'static, str>),
    EncodingError(Cow<'static, str>),
    DepthExceed(Cow<'static, str>),
    Unsupported(Cow<'static, str>),
    NotAllowed(Cow<'static, str>),
    Unknown(Cow<'static, str>),
    StructVersionMismatch(Cow<'static, str>),
}

Error type for Fory serialization and deserialization operations.

IMPORTANT: Always Use Static Constructor Functions

DO NOT construct error variants directly using the enum syntax. ALWAYS use the provided static constructor functions instead.

Why Use Static Functions?

The static constructor functions provide:

• Automatic type conversion via Into<Cow<'static, str>>
• Consistent error creation across the codebase
• Better ergonomics (no need for manual .into() calls)
• Future-proof API if error construction logic needs to change

Examples

use fory_core::error::Error;

// ✅ CORRECT: Use static functions
let err = Error::type_error("Expected string type");
let err = Error::invalid_data(format!("Invalid value: {}", 42));
let err = Error::type_mismatch(1, 2);

// ❌ WRONG: Do not construct directly
// let err = Error::TypeError("Expected string type".into());
// let err = Error::InvalidData(format!("Invalid value: {}", 42).into());

Available Constructor Functions

• Error::type_mismatch - For type ID mismatches
• Error::buffer_out_of_bound - For buffer boundary violations
• Error::encode_error - For encoding failures
• Error::invalid_data - For invalid or corrupted data
• Error::invalid_ref - For invalid reference IDs
• Error::unknown_enum - For unknown enum variants
• Error::type_error - For general type errors
• Error::encoding_error - For encoding format errors
• Error::depth_exceed - For exceeding maximum nesting depth
• Error::unsupported - For unsupported operations
• Error::not_allowed - For disallowed operations
• Error::unknown - For generic errors

Debug Mode: FORY_PANIC_ON_ERROR

For easier debugging, you can set the FORY_PANIC_ON_ERROR environment variable to make the program panic at the exact location where an error is created. This helps identify the error source with a full stack trace.

RUST_BACKTRACE=1 FORY_PANIC_ON_ERROR=1 cargo run
# or
RUST_BACKTRACE=1 FORY_PANIC_ON_ERROR=true cargo test

When enabled, any error created via the static constructor functions will panic immediately with the error message, allowing you to see the exact call stack in your debugger or panic output. Use RUST_BACKTRACE=1 together with FORY_PANIC_ON_ERROR to get a full stack trace showing exactly where the error was created.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

TypeMismatch(Cow<'static, str>)

Type mismatch between local and remote type IDs.

Do not construct this variant directly; use Error::type_mismatch instead.

BufferOutOfBound(usize, usize, usize)

Buffer boundary violation during read/write operations.

Do not construct this variant directly; use Error::buffer_out_of_bound instead.

EncodeError(Cow<'static, str>)

Error during data encoding.

Do not construct this variant directly; use Error::encode_error instead.

InvalidData(Cow<'static, str>)

Invalid or corrupted data encountered.

Do not construct this variant directly; use Error::invalid_data instead.

InvalidRef(Cow<'static, str>)

Invalid reference ID encountered.

Do not construct this variant directly; use Error::invalid_ref instead.

UnknownEnum(Cow<'static, str>)

Unknown enum variant encountered.

Do not construct this variant directly; use Error::unknown_enum instead.

TypeError(Cow<'static, str>)

General type-related error.

Do not construct this variant directly; use Error::type_error instead.

EncodingError(Cow<'static, str>)

Error in encoding format or conversion.

Do not construct this variant directly; use Error::encoding_error instead.

DepthExceed(Cow<'static, str>)

Maximum nesting depth exceeded.

Do not construct this variant directly; use Error::depth_exceed instead.

Unsupported(Cow<'static, str>)

Unsupported operation or feature.

Do not construct this variant directly; use Error::unsupported instead.

NotAllowed(Cow<'static, str>)

Operation not allowed in current context.

Do not construct this variant directly; use Error::not_allowed instead.

Unknown(Cow<'static, str>)

Generic unknown error.

Do not construct this variant directly; use Error::unknown instead.

StructVersionMismatch(Cow<'static, str>)

Struct version mismatch between local and remote schemas.

Do not construct this variant directly; use Error::struct_version_mismatch instead.

Implementations

impl Error

pub fn type_mismatch(type_a: u32, type_b: u32) -> Self

Creates a new Error::TypeMismatch with the given type IDs.

The error message will display both the original registered ID and the internal type name for user-registered types, making debugging easier.

If FORY_PANIC_ON_ERROR environment variable is set, this will panic with the error message.

Example

use fory_core::error::Error;

let err = Error::type_mismatch(1, 2);

pub fn buffer_out_of_bound( offset: usize, length: usize, capacity: usize, ) -> Self

Creates a new Error::BufferOutOfBound with the given bounds.

If FORY_PANIC_ON_ERROR environment variable is set, this will panic with the error message.

Example

use fory_core::error::Error;

let err = Error::buffer_out_of_bound(10, 20, 25);

pub fn encode_error<S: Into<Cow<'static, str>>>(s: S) -> Self

Creates a new Error::EncodeError from a string or static message.

If FORY_PANIC_ON_ERROR environment variable is set, this will panic with the error message.

Example

use fory_core::error::Error;

let err = Error::encode_error("Failed to encode");
let err = Error::encode_error(format!("Failed to encode field {}", "name"));

pub fn invalid_data<S: Into<Cow<'static, str>>>(s: S) -> Self

Creates a new Error::InvalidData from a string or static message.

If FORY_PANIC_ON_ERROR environment variable is set, this will panic with the error message.

Example

use fory_core::error::Error;

let err = Error::invalid_data("Invalid data format");
let err = Error::invalid_data(format!("Invalid data at position {}", 42));

pub fn invalid_ref<S: Into<Cow<'static, str>>>(s: S) -> Self

Creates a new Error::InvalidRef from a string or static message.

If FORY_PANIC_ON_ERROR environment variable is set, this will panic with the error message.

Example

use fory_core::error::Error;

let err = Error::invalid_ref("Invalid reference");
let err = Error::invalid_ref(format!("Invalid ref id {}", 123));

pub fn unknown_enum<S: Into<Cow<'static, str>>>(s: S) -> Self

Creates a new Error::UnknownEnum from a string or static message.

If FORY_PANIC_ON_ERROR environment variable is set, this will panic with the error message.

Example

use fory_core::error::Error;

let err = Error::unknown_enum("Unknown enum variant");
let err = Error::unknown_enum(format!("Unknown variant {}", 5));

pub fn type_error<S: Into<Cow<'static, str>>>(s: S) -> Self

Creates a new Error::TypeError from a string or static message.

If FORY_PANIC_ON_ERROR environment variable is set, this will panic with the error message.

Example

use fory_core::error::Error;

let err = Error::type_error("Type error");
let err = Error::type_error(format!("Expected type {}", "String"));

pub fn encoding_error<S: Into<Cow<'static, str>>>(s: S) -> Self

Creates a new Error::EncodingError from a string or static message.

If FORY_PANIC_ON_ERROR environment variable is set, this will panic with the error message.

Example

use fory_core::error::Error;

let err = Error::encoding_error("Encoding failed");
let err = Error::encoding_error(format!("Failed to encode as {}", "UTF-8"));

pub fn depth_exceed<S: Into<Cow<'static, str>>>(s: S) -> Self

Creates a new Error::DepthExceed from a string or static message.

If FORY_PANIC_ON_ERROR environment variable is set, this will panic with the error message.

Example

use fory_core::error::Error;

let err = Error::depth_exceed("Max depth exceeded");
let err = Error::depth_exceed(format!("Depth {} exceeds max {}", 100, 64));

pub fn unsupported<S: Into<Cow<'static, str>>>(s: S) -> Self

Creates a new Error::Unsupported from a string or static message.

If FORY_PANIC_ON_ERROR environment variable is set, this will panic with the error message.

Example

use fory_core::error::Error;

let err = Error::unsupported("Unsupported operation");
let err = Error::unsupported(format!("Type {} not supported", "MyType"));

pub fn not_allowed<S: Into<Cow<'static, str>>>(s: S) -> Self

Creates a new Error::NotAllowed from a string or static message.

If FORY_PANIC_ON_ERROR environment variable is set, this will panic with the error message.

Example

use fory_core::error::Error;

let err = Error::not_allowed("Operation not allowed");
let err = Error::not_allowed(format!("Cannot perform {}", "delete"));

pub fn struct_version_mismatch<S: Into<Cow<'static, str>>>(s: S) -> Self

Creates a new Error::StructVersionMismatch from a string or static message.

If FORY_PANIC_ON_ERROR environment variable is set, this will panic with the error message.

Example

use fory_core::error::Error;

let err = Error::struct_version_mismatch("Version mismatch");
let err = Error::struct_version_mismatch(format!("Class {} version mismatch", "Foo"));

pub fn unknown<S: Into<Cow<'static, str>>>(s: S) -> Self

Creates a new Error::Unknown from a string or static message.

This function is a convenient way to produce an error message from a literal, String, or any type that can be converted into a Cow<'static, str>.

If FORY_PANIC_ON_ERROR environment variable is set, this will panic with the error message.

Example

use fory_core::error::Error;

let err = Error::unknown("Something went wrong");
let err = Error::unknown(format!("ID:{} not found", 1));

pub fn enhance_type_error<T: ?Sized + 'static>(err: Error) -> Error

Enhances a Error::TypeError with additional type name information.

If the error is a TypeError, appends the type name to the message. Otherwise, returns the error unchanged.

Example

use fory_core::error::Error;

let err = Error::type_error("Type not registered");
let enhanced = Error::enhance_type_error::<String>(err);
// Result: "Type not registered (type: alloc::string::String)"

Trait Implementations

impl Debug for Error

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Error

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for Error

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0: use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0: replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.