Exceptions

All classes are available directly from bytespec and from bytespec.errors. Practical examples: Handling errors.

Exception
└── BytespecError
    ├── SchemaError
    ├── EncodeError
    └── DecodeError

exception bytespec.BytespecError

Common base class for schema, encoding, and decoding errors.

The common base class for library errors, a subclass of Exception.

exception bytespec.SchemaError

Bases: BytespecError

Unsupported or conflicting model or codec types/settings.

Usually raised when declaring a model or creating a codec. Some configuration errors, such as a non-text string encoding, surface during writing or reading.

An unsupported or conflicting schema/codec configuration.

Raised for an unsupported type/union, an unresolvable annotation, invalid indices, flags, defaults, numeric specs, or a codec override. Flags are checked for uniqueness and fit within the selected size; optional fields must have a flag, and required fields must not. Conflicting inherited custom headers are also rejected unless the subclass makes an explicit choice.

Unsupported header element encodings and prefixes, an invalid constructor type, a negative FixedBytesCodec length, an invalid struct format, and an unknown encoding name also raise this error. An existing Python codec unsuitable for text (such as base64_codec) is rejected when writing or reading a string, not necessarily when declaring the model.

exception bytespec.EncodeError

Bases: BytespecError

The value cannot be written in the selected binary representation.

For example, a number outside its range, a length prefix overflow, text that cannot be represented in the encoding, or a missing required value.

The value cannot be written in the specified format.

Includes an integer/varint outside its range, a float or length prefix overflow, a text encoding error, and a FixedBytesCodec length mismatch. A constructor outside the range of its encoding also falls into this category. The model also rejects a deleted attribute and None in a required field.

exception bytespec.DecodeError

Bases: BytespecError

The buffer is incomplete or does not match the expected binary format.

For example, an incorrect constructor, missing bytes, an invalid value, or data after the message when calling ProtoModel.decode().

The buffer cannot be read using the specified schema.

Includes an incomplete header, a constructor mismatch, a declared length exceeding the buffer, a truncated field, reading beyond the model contents, and an invalid bool, text, ISO datetime, enum, or varint. decode() rejects bytes after the message. Unknown trailing data within the declared length follows different rules — Boundaries and unknown data.

Missing Flags when optional fields are declared or inherited raises SchemaError at class declaration. A subclass’s new header is checked even when no new fields are declared. Header element kinds are not separately checked for uniqueness — What is checked in 0.1.0.

Diagnostics and standard Python exceptions

When handling a field’s EncodeError/DecodeError, the model adds the class and field names to the exception text. The exception object itself is not replaced. Wrapped struct.error, Unicode errors, and enum/datetime conversion errors are preserved in __cause__.

Decoder offsets generally refer to the supplied buffer. For a list item, this is a separate buffer containing the list contents, not the original message. Exceptions do not have separate field or offset attributes.

Invalid model call arguments, a missing required field, and an invalid factory return type raise TypeError. A negative offset raises ValueError. Explicit model arguments are not fully validated: values of an entirely different type and custom codec errors may raise standard Python exceptions. Validator exceptions propagate without wrapping during model creation and reading — Validating model values.