Exceptions

All Jetliner exceptions inherit from JetlinerError, allowing you to catch any library-specific error:

try:
    df = jetliner.read_avro("data.avro")
except jetliner.JetlinerError as e:
    print(f"Jetliner error: {e}")

Exceptions that map to Python builtins also inherit from those builtins for idiomatic handling:

try:
    df = jetliner.read_avro("missing.avro")
except FileNotFoundError:
    print("File not found!")

Base Exception

jetliner.JetlinerError(message, variant='Unknown')

Bases: Exception

Base exception for all Jetliner errors.

Users can catch this to handle any Jetliner-specific error.

Attributes:

Name	Type	Description
message	str	Human-readable error message.
variant	str	The specific error variant (e.g., "InvalidData", "NotFound").

Functions

to_dict()

Convert exception attributes to a dictionary.

Decoding and Parsing

jetliner.DecodeError(message, variant='Decode', path=None, block_index=None, record_index=None, file_offset=None, block_offset=None)

Bases: JetlinerError

Error decoding Avro record data.

Attributes:

Name	Type	Description
message	str	Human-readable error message.
variant	str	The specific decode error variant (e.g., "InvalidData", "InvalidUtf8").
path	str | None	The file path where the error occurred (if available).
block_index	int | None	The block number where the error occurred.
record_index	int | None	The record number within the block.
file_offset	int | None	The absolute file offset where the error occurred.
block_offset	int | None	The offset within the block where the error occurred.

Functions

to_dict()

Convert exception attributes to a dictionary.

jetliner.ParseError(message, variant='Parse', path=None, file_offset=None)

Bases: JetlinerError

Error parsing Avro file structure.

Raised when the file header, magic bytes, or sync markers are invalid.

Attributes:

Name	Type	Description
message	str	Human-readable error message.
variant	str	The specific parse error variant (e.g., "InvalidMagic", "InvalidSyncMarker").
path	str | None	The file path where the error occurred (if available).
file_offset	int | None	The file offset where the error occurred.

Functions

to_dict()

Convert exception attributes to a dictionary.

Schema and Codec

jetliner.SchemaError(message, variant='Schema', path=None, schema_context=None)

Bases: JetlinerError

Error with Avro schema.

Raised for invalid schemas, unsupported types, or schema incompatibilities.

Attributes:

Name	Type	Description
message	str	Human-readable error message.
variant	str	The specific schema error variant (e.g., "InvalidSchema", "UnsupportedType").
path	str | None	The file path where the error occurred (if available).
schema_context	str | None	Optional additional context (e.g., field name, type).

Functions

to_dict()

Convert exception attributes to a dictionary.

jetliner.CodecError(message, variant='Codec', path=None, codec='', block_index=None, file_offset=None)

Bases: JetlinerError

Error with compression codec.

Raised for unsupported codecs or decompression failures.

Attributes:

Name	Type	Description
message	str	Human-readable error message.
variant	str	The specific codec error variant (e.g., "UnsupportedCodec", "DecompressionError").
path	str | None	The file path where the error occurred (if available).
codec	str	The codec name that caused the error.
block_index	int | None	The block number where the error occurred (if available).
file_offset	int | None	The file offset where the error occurred (if available).

Functions

to_dict()

Convert exception attributes to a dictionary.

Source Access

jetliner.SourceError(message, variant='Source', path=None)

Bases: JetlinerError

Error accessing data source.

Raised for I/O errors, S3 errors, and other source access issues. Note: FileNotFoundError, PermissionError, and AuthenticationError are raised for those specific cases.

Attributes:

Name	Type	Description
message	str	Human-readable error message.
variant	str	The specific source error variant (e.g., "S3Error", "Io").
path	str | None	The file path that caused the error.

Functions

to_dict()

Convert exception attributes to a dictionary.

jetliner.AuthenticationError(message, variant='AuthenticationFailed', path=None)

Bases: JetlinerError

S3/cloud authentication failure.

Raised when authentication fails (invalid credentials, expired tokens, etc.). This is distinct from PermissionError which is for valid credentials with insufficient permissions.

Attributes:

Name	Type	Description
message	str	Human-readable error message.
variant	str	The specific authentication error variant.
path	str | None	The file path where the error occurred (if available).

Functions

to_dict()

Convert exception attributes to a dictionary.

jetliner.FileNotFoundError(message, variant='NotFound', path=None)

Bases: JetlinerError, FileNotFoundError

File or S3 object not found.

Inherits from both JetlinerError and builtins.FileNotFoundError, allowing idiomatic Python exception handling::

try:
    df = jetliner.read_avro("missing.avro")
except FileNotFoundError:
    print("File not found!")

Attributes:

Name	Type	Description
message	str	Human-readable error message.
variant	str	The specific error variant.
path	str | None	The file path that was not found.
errno	int	Error number (2 = ENOENT for file not found).
filename	str | None	The file path that was not found (alias for path).

Functions

to_dict()

Convert exception attributes to a dictionary.

jetliner.PermissionError(message, variant='PermissionDenied', path=None)

Bases: JetlinerError, PermissionError

Permission denied (but authenticated).

Raised when credentials are valid but lack permission for the requested operation. This is distinct from AuthenticationError which is for invalid/missing credentials.

Inherits from both JetlinerError and builtins.PermissionError, allowing idiomatic Python exception handling::

try:
    df = jetliner.read_avro("s3://restricted-bucket/file.avro")
except PermissionError:
    print("Access denied!")

Attributes:

Name	Type	Description
message	str	Human-readable error message.
variant	str	The specific error variant.
path	str | None	The file path that caused the error.
errno	int	Error number (13 = EACCES for permission denied).
filename	str | None	The file path that caused the error (alias for path).

Functions

to_dict()

Convert exception attributes to a dictionary.

Configuration

jetliner.ConfigurationError(message, variant='Configuration')

Bases: JetlinerError, ValueError

Invalid configuration parameters.

Raised when invalid parameters are passed to Jetliner functions (e.g., invalid batch size, unsupported options).

Inherits from both JetlinerError and builtins.ValueError, allowing idiomatic Python exception handling::

try:
    reader = jetliner.AvroReader("file.avro", batch_size=-1)
except ValueError:
    print("Invalid configuration!")

Attributes:

Name	Type	Description
message	str	Human-readable error message.
variant	str	The specific error variant.

Functions

to_dict()

Convert exception attributes to a dictionary.

Error Information

jetliner.BadBlockError

Structured error information from skip mode reading.

When reading with ignore_errors=True, errors are accumulated rather than causing immediate failure. After iteration completes, errors are accessible via the reader's .errors property as a list of BadBlockError objects.

Attributes:

Name	Type	Description
kind	str	Error type string. One of: "InvalidSyncMarker" - Block sync marker doesn't match file header "DecompressionFailed(codec)" - Codec decompression failed "BlockParseFailed" - Block metadata couldn't be parsed "RecordDecodeFailed" - Record data couldn't be decoded "SchemaViolation" - Data doesn't match expected schema
block_index	int	Block number where the error occurred (0-based).
record_index	int | None	Record number within the block, if applicable (0-based).
file_offset	int	Byte offset in the file where the error occurred.
message	str	Human-readable error description.
filepath	str | None	Source file path, if known (useful for multi-file reads).

Examples:

>>> with jetliner.AvroReader("file.avro", ignore_errors=True) as reader:
...     for df in reader:
...         process(df)
...
...     for err in reader.errors:
...         print(f"[{err.kind}] Block {err.block_index}: {err.message}")
...         # Or as dict for logging/serialization
...         log_error(err.to_dict())

Attributes

block_index instance-attribute

Block index where error occurred (0-based).

file_offset instance-attribute

Byte offset in the file where error occurred.

filepath instance-attribute

Source file path, or None if unknown.

kind instance-attribute

Error type string (e.g., "InvalidSyncMarker", "DecompressionFailed(snappy)").

message instance-attribute

Human-readable error message.

record_index instance-attribute

Record index within block (0-based), or None if not applicable.

Functions

__repr__()

Return a detailed string representation of the error.

__str__()

Return a user-friendly string representation of the error.

to_dict()

Convert the error to a Python dictionary.

Returns:

Type	Description
dict[str, Any]	A dict with keys: kind, block_index, record_index, file_offset, message, filepath.

Examples:

>>> err_dict = err.to_dict()
>>> print(err_dict["kind"])  # "InvalidSyncMarker"
>>> print(err_dict["block_index"])  # 5