Pipeline Exceptions

Exception hierarchy for the pipeline (workflow execution) subsystem.

Exception Hierarchy

KstlibError
└── PipelineError
    ├── PipelineConfigError (also ValueError)
    ├── PipelineAbortedError
    └── StepError
        ├── StepTimeoutError
        └── StepImportError

Base Exception

exception kstlib.pipeline.exceptions.PipelineError

Bases: KstlibError

Base exception for all pipeline module errors.

All pipeline-specific exceptions inherit from this class, allowing for easy catching of any pipeline error.

Configuration Errors

exception kstlib.pipeline.exceptions.PipelineConfigError

Bases: PipelineError, ValueError

Pipeline configuration is invalid.

Raised when the pipeline or step configuration contains invalid values, missing required fields, or constraint violations.

Raised when pipeline or step configuration is invalid (missing fields, constraint violations, unknown types).

Execution Errors

exception kstlib.pipeline.exceptions.PipelineAbortedError(step_name, reason)

Bases: PipelineError

Pipeline execution was aborted due to fail_fast policy.

Raised when a step fails and the error policy is fail_fast, causing the remaining steps to be skipped.

step_name

Name of the step that caused the abort.

reason

Description of why the step failed.

__init__(self, step_name: 'str', reason: 'str') → 'None' -> None

Initialize PipelineAbortedError.

Parameters:

• step_name (str) – Name of the step that caused the abort.

• reason (str) – Description of why the step failed.

exception kstlib.pipeline.exceptions.StepError(step_name, reason)

Bases: PipelineError

A pipeline step failed during execution.

step_name

Name of the step that failed.

reason

Description of the failure.

__init__(self, step_name: 'str', reason: 'str') → 'None' -> None

Initialize StepError.

Parameters:

• step_name (str) – Name of the step that failed.

• reason (str) – Description of the failure.

exception kstlib.pipeline.exceptions.StepTimeoutError(step_name, timeout)

Bases: StepError

A pipeline step exceeded its timeout.

step_name

Name of the step that timed out.

timeout

The timeout value in seconds.

__init__(self, step_name: 'str', timeout: 'float') → 'None' -> None

Initialize StepTimeoutError.

Parameters:

• step_name (str) – Name of the step that timed out.

• timeout (float) – The timeout value in seconds.

exception kstlib.pipeline.exceptions.StepImportError(step_name, target)

Bases: StepError

Failed to import a callable target for a step.

step_name

Name of the step with the import failure.

target

The import target string that failed.

__init__(self, step_name: 'str', target: 'str') → 'None' -> None

Initialize StepImportError.

Parameters:

• step_name (str) – Name of the step with the import failure.

• target (str) – The import target string (e.g. “module.path:function”).

Usage Examples

from kstlib.pipeline.exceptions import (
    PipelineError,
    PipelineAbortedError,
    PipelineConfigError,
    StepError,
    StepTimeoutError,
    StepImportError,
)

try:
    result = runner.run()
except PipelineAbortedError as e:
    print(f"Pipeline aborted at step '{e.step_name}': {e.reason}")
except StepTimeoutError as e:
    print(f"Step '{e.step_name}' timed out after {e.timeout}s")
except StepImportError as e:
    print(f"Cannot import '{e.target}' for step '{e.step_name}'")
except PipelineConfigError as e:
    print(f"Invalid config: {e}")
except PipelineError as e:
    print(f"Pipeline error: {e}")