Skip to content

Exceptions

This reference covers the error types exported from firecube.ingestor.api. Ingestor-layer errors inherit from IngestorError; ManifestError, SchemaDriftError, and StorageError are shared error types re-exported through the same facade.

ExtentUnknownError is the core resolver error raised when a regular axis has no fixed extent.

UnboundedAxisError is the ConfigurationError subclass the engine raises for the same unbounded-axis case.

MissingIrregularCoordinateError, DuplicateIrregularCoordinateError, and NoDiscoveredItemsError are raised during IrregularTimeAxis(values=AUTO) discovery.

Name Description
IngestorError Base exception for all ingestor-layer errors.
ConfigurationError Invalid or conflicting configuration was supplied for a run.
ExtentUnknownError Raised when a regular axis has no fixed extent.
UnboundedAxisError Raised when a regular axis has no fixed extent but one is required.
MissingIrregularCoordinateError An irregular time-axis item lacks a resolvable coordinate.
DuplicateIrregularCoordinateError Two discovered items resolve to the same irregular-axis coordinate.
NoDiscoveredItemsError Discovery found no items for an irregular time axis.
IndexedWriteCompilationError IndexedWrite compilation failed for a coordinate-bound write intent.
SchemaDriftError Existing Zarr array metadata drifted from the declared schema.
SchemaSizeMismatchError Raised when an existing Zarr array's shape is smaller than the global expected size.
ManifestError Manifest read/write/update operation failed.
StorageError Storage backend operation failed (local, S3, etc.).
ResumeConflictError Existing data conflicts with this run's resume/overwrite settings.
RangeOverlapError Raised when a new slot-range invocation overlaps with an active non-terminal run.
WriteIntentRangeError Raised when a WriteIntent's ts_index falls outside the assigned slot range.

Ingestor Errors

firecube.ingestor.api.IngestorError

Bases: FirecubeError

Base exception for all ingestor-layer errors.

firecube.ingestor.api.ConfigurationError

Bases: FirecubeError

Invalid or conflicting configuration was supplied for a run.

Raised during option validation and pre-write checks, e.g. unknown or malformed options, missing required inputs, or an existing store whose layout conflicts with the plugin's declaration.

firecube.ingestor.api.ExtentUnknownError

Bases: ValueError

Raised when a regular axis has no fixed extent.

Examples:

>>> raise ExtentUnknownError(
...     "regular axis has no fixed extent: set either end_date or slot_count"
... )
Traceback (most recent call last):
...
ExtentUnknownError: regular axis has no fixed extent: set either end_date or slot_count

firecube.ingestor.api.UnboundedAxisError

Bases: ConfigurationError

Raised when a regular axis has no fixed extent but one is required.

Set RegularTimeAxis(end_date=...) or slot_count=... in the declared IndexSpec to give the axis a fixed extent.

Parameters:

Name Type Description Default
group str

Name of the index group whose axis lacks a fixed extent.

 required

firecube.ingestor.api.SchemaSizeMismatchError

Bases: IngestorError

Raised when an existing Zarr array's shape is smaller than the global expected size.

Existing arrays mismatch the plan. Either delete them or update the plan to match.

firecube.ingestor.api.ResumeConflictError

Bases: IngestorError

Existing data conflicts with this run's resume/overwrite settings.

Raised when previously ingested entries for the product are detected but the run was started without resume_existing or force_reingest, or lacks the slice options needed to match existing entries safely.

firecube.ingestor.api.RangeOverlapError

Bases: ResumeConflictError

Raised when a new slot-range invocation overlaps with an active non-terminal run.

Overlapping ranges risk Zarr chunk-boundary corruption. Abandon the conflicting run first: firecube chunks runs abandon ...

firecube.ingestor.api.WriteIntentRangeError

Bases: IngestorError

Raised when a WriteIntent's ts_index falls outside the assigned slot range.

This is a correctness violation — the plugin filter is advisory; this error is the mandatory backstop. NEVER silently drop out-of-range intents.

Irregular Axis Discovery Errors

These errors are raised when IrregularTimeAxis(values=AUTO) discovery fails. All three inherit from ConfigurationError.

firecube.ingestor.api.MissingIrregularCoordinateError

Bases: ConfigurationError

An irregular time-axis item lacks a resolvable coordinate.

firecube.ingestor.api.DuplicateIrregularCoordinateError

Bases: ConfigurationError

Two discovered items resolve to the same irregular-axis coordinate.

firecube.ingestor.api.NoDiscoveredItemsError

Bases: ConfigurationError

Discovery found no items for an irregular time axis.

Shared Errors

firecube.ingestor.api.ManifestError

Bases: FirecubeError

Manifest read/write/update operation failed.

firecube.ingestor.api.SchemaDriftError

Bases: FirecubeError

Existing Zarr array metadata drifted from the declared schema.

Compared fields: dtype, rank, shape[1:], chunks, fill_value. The time axis shape[0] is handled specially: smaller fails, larger warns.

firecube.ingestor.api.StorageError

Bases: FirecubeError

Storage backend operation failed (local, S3, etc.).

IndexedWrite Compilation Errors

IndexedWriteCompilationError is raised when the engine cannot map an IndexedWrite.coordinate to a slot index at compile time.

firecube.ingestor.api.IndexedWriteCompilationError

Bases: ValueError

IndexedWrite compilation failed for a coordinate-bound write intent.

See Also