Skip to content

Handle Python errors

A read can fail when opening a table, preparing a query, or consuming batches. Keep error handling around the whole read:

import pyarrow
from delta_arrow_reader import DeltaReaderError, DeltaTable

try:
    table = DeltaTable("/path/to/table")
    with table.to_reader(limit=10) as reader:
        result = reader.read_all()
except DeltaReaderError as error:
    print(f"Could not prepare the read: {error}")
except pyarrow.ArrowException as error:
    print(f"Could not read batches: {error}")

Opening or planning can raise DeltaReaderError. Failures during iteration or read_all() use PyArrow exceptions. Invalid Python arguments can raise TypeError or ValueError; correct the argument before retrying.

If a read fails after returning some batches, the result is incomplete. The with block closes the reader when the block finishes or an exception occurs.

Inspect a reader error

phase tells you where the read stopped, and code identifies the kind of failure. For example, phase=table_location with code=invalid_table_location points to a problem with the supplied path or URL. Check that you are using the table's directory, which contains _delta_log, rather than a data file. For cloud tables, also check the storage settings for S3 or Azure.

reason and source_kind provide more detail when available. These attributes work even when logging is disabled; you can include them when reporting a problem.

DeltaReaderError

Bases: Exception

A failure while opening a table or preparing a query.

Inspect phase and code to identify the failure without parsing the message. Messages omit sensitive details such as table paths and storage credentials.

Attributes:

Name Type Description
phase str

The stage that failed, such as schema or datafusion.
code str

The error category, such as schema_conversion or sql_planning.
reason str | None

The Core failure reason, or None for a binding-owned failure.
source_kind str | None

The safe Core source category, or None when unavailable.

Invalid Python arguments can raise built-in exceptions such as TypeError or ValueError instead. Failures while consuming a PyArrow reader use PyArrow exceptions; catch those around iteration or read_all() as well.

phase instance-attribute 

phase: str

code instance-attribute 

code: str

reason instance-attribute 

reason: str | None

source_kind instance-attribute 

source_kind: str | None

Get more context

Enable logging to see reader progress or collect more detail while investigating a failure.