#[non_exhaustive]pub enum DeserializeErrorKind {
Show 23 variants
UnexpectedChar {
ch: char,
expected: &'static str,
},
UnexpectedEof {
expected: &'static str,
},
InvalidUtf8 {
context: [u8; 16],
context_len: u8,
},
UnexpectedToken {
got: Cow<'static, str>,
expected: &'static str,
},
TypeMismatch {
expected: &'static Shape,
got: Cow<'static, str>,
},
ShapeMismatch {
expected: &'static Shape,
got: &'static Shape,
},
UnknownField {
field: Cow<'static, str>,
suggestion: Option<&'static str>,
},
UnknownVariant {
variant: Cow<'static, str>,
enum_shape: &'static Shape,
},
NoMatchingVariant {
enum_shape: &'static Shape,
input_kind: &'static str,
},
MissingField {
field: &'static str,
container_shape: &'static Shape,
},
DuplicateField {
field: Cow<'static, str>,
first_span: Option<Span>,
},
NumberOutOfRange {
value: Cow<'static, str>,
target_type: &'static str,
},
InvalidValue {
message: Cow<'static, str>,
},
CannotBorrow {
reason: Cow<'static, str>,
},
Reflect {
kind: ReflectErrorKind,
context: &'static str,
},
Unsupported {
message: Cow<'static, str>,
},
Io {
message: Cow<'static, str>,
},
Solver {
message: Cow<'static, str>,
},
Validation {
field: &'static str,
message: Cow<'static, str>,
},
Bug {
error: Cow<'static, str>,
context: &'static str,
},
Alloc {
shape: &'static Shape,
operation: &'static str,
},
Materialize {
expected: &'static Shape,
actual: &'static Shape,
},
RawCaptureNotSupported {
shape: &'static Shape,
},
}Expand description
Specific kinds of deserialization errors.
Uses Cow<'static, str> to avoid allocations when possible while still
supporting owned strings when needed (e.g., field names from input).
Variants (Non-exhaustive)§
This enum is marked as non-exhaustive
UnexpectedChar
Unexpected character encountered by the parser.
Level: Parser (e.g., JsonParser)
This happens when the parser encounters a character that doesn’t fit the format’s grammar at the current position.
{"name": @invalid}
^
unexpected character '@', expected valueFields
UnexpectedEof
Unexpected end of input.
Level: Parser (e.g., JsonParser)
The input ended before a complete value could be parsed.
{"name": "Alice
^
unexpected EOF, expected closing quoteInvalidUtf8
Invalid UTF-8 sequence in input.
Level: Parser (e.g., JsonParser)
The input contains bytes that don’t form valid UTF-8.
{"name": "hello\xff world"}
^^^^
invalid UTF-8 sequenceFields
UnexpectedToken
Unexpected token from parser.
Level: Deserializer (FormatDeserializer)
The parser produced a valid token, but it’s not what the deserializer expected at this point given the target Rust type.
// Deserializing into Vec<i32>
{"not": "an array"}
^
unexpected token: got object, expected arrayNot to be confused with:
UnexpectedChar: parser-level, about invalid syntaxTypeMismatch: about shape expectations, not token types
Fields
TypeMismatch
Type mismatch: expected a shape, got something else from the parser.
Level: Deserializer (FormatDeserializer)
We know the target Rust type (Shape), but the parser gave us something incompatible.
// Deserializing into struct User { age: u32 }
{"age": "not a number"}
^^^^^^^^^^^^^^
type mismatch: expected u32, got stringFields
ShapeMismatch
Shape mismatch: expected one Rust type, but the code path requires another.
Level: Deserializer (FormatDeserializer)
This is an internal routing error - the deserializer was asked to deserialize into a type that doesn’t match what the current code path expects. For example, calling enum deserialization on a struct.
// Internal error: deserialize_enum called but shape is a struct
shape mismatch: expected enum, got struct UserNot to be confused with:
TypeMismatch: about parser output vs expected typeUnexpectedToken: about token types from parser
Fields
UnknownField
Unknown field in struct.
Level: Deserializer (FormatDeserializer)
The input contains a field name that doesn’t exist in the target struct
and the struct doesn’t allow unknown fields (no #[facet(deny_unknown_fields)]
or similar).
// Deserializing into struct User { name: String }
{"name": "Alice", "age": 30}
^^^^^
unknown field `age`Fields
UnknownVariant
Unknown enum variant.
Level: Deserializer (FormatDeserializer)
The input specifies a variant name that doesn’t exist in the target enum.
// Deserializing into enum Status { Active, Inactive }
"Pending"
^^^^^^^^^
unknown variant `Pending` for enum `Status`Fields
NoMatchingVariant
No variant matched for untagged enum.
Level: Deserializer (FormatDeserializer)
For #[facet(untagged)] enums, we try each variant in order.
This error means none of them matched the input.
// Deserializing into #[facet(untagged)] enum Value { Int(i32), Str(String) }
[1, 2, 3]
^^^^^^^^^
no matching variant for enum `Value` with array inputFields
MissingField
Missing required field.
Level: Deserializer (FormatDeserializer)
A struct field without a default value was not provided in the input.
// Deserializing into struct User { name: String, email: String }
{"name": "Alice"}
^
missing field `email` in type `User`Fields
DuplicateField
Duplicate field in input.
Level: Deserializer (FormatDeserializer)
The same field appears multiple times in the input.
{"name": "Alice", "name": "Bob"}
^^^^^^
duplicate field `name` (first occurrence at offset 1)Fields
NumberOutOfRange
Number out of range for target type.
Level: Deserializer (FormatDeserializer)
The input contains a valid number, but it doesn’t fit in the target type.
// Deserializing into u8
256
^^^
number `256` out of range for u8Fields
InvalidValue
Invalid value for the target type.
Level: Deserializer (FormatDeserializer)
The value is syntactically valid but semantically wrong for the target type. Used for things like invalid enum discriminants, malformed UUIDs, etc.
// Deserializing into Uuid
"not-a-valid-uuid"
^^^^^^^^^^^^^^^^^^
invalid value: expected UUID formatCannotBorrow
Cannot borrow string from input.
Level: Deserializer (FormatDeserializer)
When deserializing into &str or Cow<str>, the string in the input
required processing (e.g., escape sequences) and cannot be borrowed.
// Deserializing into &str
"hello\nworld"
^^^^^^^^^^^^^^
cannot borrow: string contains escape sequencesReflect
Error from the reflection system.
Level: Deserializer (via facet-reflect)
These errors come from Partial operations like field access,
variant selection, or type building.
Note: The path is stored at the DeserializeError level, not here.
When converting from ReflectError, the path is extracted and stored
in DeserializeError.path.
Fields
kind: ReflectErrorKindThe specific kind of reflection error
Unsupported
Feature not implemented.
Level: Deserializer or Parser
The requested operation is not yet implemented. This is used for known gaps in functionality, not for invalid input.
// Trying to deserialize a type that's not yet supported
unsupported: multi-element tuple variants in flatten not yet supportedIo
I/O error during streaming deserialization.
Level: Parser
For parsers that read from streams, this wraps I/O errors.
Solver
Error from the flatten solver.
Level: Deserializer (via facet-solver)
When deserializing types with #[facet(flatten)], the solver
determines which fields go where. This error indicates solver failure.
Validation
Validation error.
Level: Deserializer (post-deserialization)
After successful deserialization, validation constraints failed.
// With #[facet(validate = "validate_age")]
{"age": -5}
^^
validation failed for field `age`: must be non-negativeFields
Bug
Internal error indicating a logic bug in facet-format or one of the crates that relies on it (facet-json,e tc.)
Alloc
Memory allocation failed.
Level: Deserializer (internal)
Failed to allocate memory for the partial value being built. This is rare but can happen with very large types or low memory.
Fields
Materialize
Shape mismatch when materializing a value.
Level: Deserializer (internal)
The shape of the built value doesn’t match the target type. This indicates a bug in the deserializer logic.
Fields
RawCaptureNotSupported
Raw capture is not supported by the current parser.
Level: Deserializer (FormatDeserializer)
Types like RawJson require capturing the raw input without parsing it.
This error occurs when attempting to deserialize such a type with a parser
that doesn’t support raw capture (e.g., streaming parsers without buffering).
// Deserializing RawJson in streaming mode
raw capture not supported: type `RawJson` requires raw capture, but the
parser does not support it (e.g., streaming mode without buffering)Implementations§
Source§impl DeserializeErrorKind
impl DeserializeErrorKind
Sourcepub const fn with_span(self, span: Span) -> DeserializeError
pub const fn with_span(self, span: Span) -> DeserializeError
Attach a span to this error kind, producing a full DeserializeError.