errors

etl_craft.core.errors

The error hierarchy, and the exit status the command line returns for each error.

Every error etl-craft raises on purpose is an EtlCraftError, and every error class has its own exit status, so a scheduler or script can tell exactly what went wrong from the status alone. ExitCode lists them all.

ExitCode

Bases: IntEnum

The exit status of an etl-craft command.

FAILURE class-attribute instance-attribute

FAILURE = 1

The work ran and did not succeed: a task or pipeline failed, or a check found problems.

UNEXPECTED class-attribute instance-attribute

UNEXPECTED = 16

An error with no class of its own, including a bug; its traceback is logged.

EtlCraftError

Bases: Exception

Base class of every error etl-craft raises; each subclass has its own exit status.

ConfigurationError

Bases: EtlCraftError

craft-connector.yml, a secret or a connection target cannot be used.

Covers a missing or invalid file, an unset secret variable, a JDBC URL or auth mode with no matching dialect, and an Engine DB that cannot be reached.

UsageError

Bases: EtlCraftError

The command line arguments are invalid.

MetadataError

Bases: EtlCraftError

A pipeline or task code does not resolve to an active CFG_ row.

GraphError

Bases: EtlCraftError

The task or pipeline dependency graph is invalid.

RunStateError

Bases: EtlCraftError

The run log is in a state the requested run cannot proceed from.

RunRefusedError

Bases: EtlCraftError

The run is not allowed in the configured mode, for example --force in remote mode.

ConnectionTestError

Bases: EtlCraftError

A connection failed its test before the run started.

EngineDbError

Bases: EtlCraftError

The Engine DB could not be initialised or changed.

MigrationError

Bases: EngineDbError

A migration failed to apply.

LockTimeoutError

Bases: EngineDbError

A cross-process lock was not acquired in time.

HandlerError

Bases: EtlCraftError

A task handler is missing or failed; the task is recorded as FAILED.

CloningError

Bases: EtlCraftError

Copying an Engine DB table into the warehouse failed; the message names the table.

RemoteUnsupportedError

Bases: EtlCraftError

A pipeline has rules a remote orchestrator does not support; the message names each.

InjectedFaultError

Bases: EtlCraftError

A named development fault selected by the caller's environment.

StaleTransitionError

Bases: EtlCraftError

A lifecycle write lost its status or owner guard; refresh the row before retrying.

SqlGuardError

Bases: HandlerError

SQL input or target state must be corrected before another attempt can succeed.

ResourceNotFoundError

Bases: EtlCraftError

An exact execution resource or its log is unavailable.