Last Updated: 3/19/2026

Pipeline Lifecycle

A Feldera pipeline progresses through multiple states during its lifetime, from initial creation through execution to shutdown. Understanding these states and transitions is essential for managing pipelines effectively.

Pipeline States

Runtime States

A pipeline’s runtime status indicates its current operational state:

• Unavailable — The pipeline has not been deployed or resources have been deallocated
• Coordination — Multi-host pipelines are coordinating between hosts
• Standby — The pipeline is waiting for activation (used when starting from a checkpoint)
• AwaitingApproval — The pipeline is waiting for explicit user approval before bootstrapping
• Initializing — The pipeline is starting up and initializing connectors
• Bootstrapping — The pipeline is rebuilding state from storage or checkpoints
• Replaying — The pipeline is replaying logged inputs after a restart
• Paused — The pipeline is running but not processing inputs
• Running — The pipeline is actively processing inputs
• Suspended — The pipeline has been suspended (transitional state before stopping)

Desired States

The desired runtime status indicates the target state the pipeline should transition to:

• Unavailable — Scale resources to zero
• Coordination — Coordinate between hosts (multi-host only)
• Standby — Wait in standby mode for activation
• Paused — Run but do not process inputs
• Running — Actively process inputs
• Suspended — Suspend execution

State Transitions

Starting a Pipeline

When you start a pipeline, it transitions through several states:

1. Unavailable → Initializing — Resources are provisioned and the pipeline process starts
2. Initializing → Bootstrapping (if storage is enabled) — The pipeline loads state from storage
3. Bootstrapping → Replaying (if fault tolerance is enabled) — The pipeline replays logged inputs
4. Replaying → Running — The pipeline begins processing new inputs

If the pipeline is started in paused mode, the final state is Paused instead of Running.

Starting from a checkpoint:

When starting from a checkpoint in object storage with the standby option enabled:

1. Unavailable → Standby — The pipeline waits in standby mode
2. Standby → Bootstrapping (after activation) — The pipeline loads the checkpoint
3. Bootstrapping → Running — The pipeline begins processing

Bootstrap policies:

When starting a pipeline, you can specify a bootstrap policy:

• allow — Automatically proceed with bootstrapping (default)
• reject — Fail if bootstrapping is required
• await_approval — Wait in AwaitingApproval state for explicit user approval

Pausing a Pipeline

Pausing a pipeline stops input processing while keeping the pipeline running:

Running → Paused

While paused:

• Input connectors stop reading data
• The pipeline maintains its state in memory or storage
• You can still push data via the API with the force flag
• Ad-hoc queries continue to work
• Output connectors remain connected

Resume the pipeline to transition back to Running.

Stopping a Pipeline

Stopping a pipeline deallocates resources and terminates the process. There are two stop modes:

Graceful stop (force=false):

1. The pipeline creates a checkpoint (if fault tolerance is enabled)
2. All connectors are gracefully shut down
3. The pipeline transitions to Suspended
4. Resources are deallocated and the state becomes Unavailable

Forced stop (force=true):

1. The pipeline immediately scales resources to zero
2. No checkpoint is created
3. The state becomes Unavailable

After stopping, you must call start() again to restart the pipeline.

Restarting a Pipeline

The restart operation is a convenience method that combines stop and start:

pipeline.restart(bootstrap_policy=BootstrapPolicy.ALLOW)

This performs a forced stop (no checkpoint) followed by a start with the specified bootstrap policy.

Managing Pipeline State

Checking Pipeline Status

Query the current runtime status:

from feldera import Pipeline, PipelineStatus
 
status = pipeline.status()
if status == PipelineStatus.RUNNING:
    print("Pipeline is running")

Wait for a specific status:

pipeline.wait_for_status(PipelineStatus.RUNNING, timeout=300)

Controlling Execution

Start the pipeline:

pipeline.start()  # Start in running state
pipeline.start_paused()  # Start in paused state
pipeline.start_standby()  # Start in standby state

Pause and resume:

pipeline.pause()  # Pause input processing
pipeline.resume()  # Resume input processing

Stop the pipeline:

pipeline.stop(force=False)  # Graceful stop with checkpoint
pipeline.stop(force=True)   # Immediate stop without checkpoint

Activation from Standby

When a pipeline starts in standby mode (typically when loading from a checkpoint), explicitly activate it:

pipeline.activate(wait=True, timeout_s=300)

This transitions the pipeline from Standby to Bootstrapping and then to Running.

Approval for Bootstrapping

When a pipeline is started with bootstrap_policy=BootstrapPolicy.AWAIT_APPROVAL, it waits in the AwaitingApproval state. Approve it to proceed:

pipeline.approve()

This is useful when you want to manually verify conditions before allowing the pipeline to bootstrap and potentially recompute large amounts of state.

Handling Errors

Deployment Errors

If a pipeline encounters an error during deployment or execution, the error is captured in the deployment_error field:

error = pipeline.deployment_error()
if error:
    print(f"Pipeline error: {error}")

Dismiss the error to allow the pipeline to be restarted:

pipeline.dismiss_error()

Program Errors

Compilation errors are stored separately in the program_error field:

program_error = pipeline.program_error()
if program_error.get("sql_compilation", {}).get("exit_code", 0) != 0:
    print("SQL compilation failed")

Completion and Idle Detection

Waiting for Completion

Block until the pipeline has processed all inputs from finite input sources:

pipeline.wait_for_completion(timeout_s=600)

This waits until:

1. All input connectors have issued end-of-input notifications
2. All received inputs have been fully processed
3. All outputs have been sent through output connectors

This method blocks indefinitely if any input connector is a streaming source (like Kafka) that never ends.

Waiting for Idle

Wait for the pipeline to become idle (no processing activity):

pipeline.wait_for_idle(
    idle_interval_s=5.0,
    timeout_s=300.0,
    poll_interval_s=0.2
)

The pipeline is considered idle when:

• The number of input records equals the number of processed records
• These counts remain unchanged for the specified idle interval

Storage Management

Clearing Storage

Clear all pipeline storage (checkpoints and state):

pipeline.clear_storage(wait=True, timeout_s=300)

Storage must be cleared before deleting a pipeline or when changing certain configuration options (like the number of workers).

Storage Status

Check the storage status:

from feldera import StorageStatus
 
status = pipeline.storage_status()
if status == StorageStatus.CLEARING:
    print("Storage is being cleared")

Storage states:

• NotBound — No storage is allocated
• Bound — Storage is allocated and ready
• Clearing — Storage is being cleared
• ClearingFailed — Storage clearing failed

Multi-Host Coordination

For multi-host pipelines (enterprise feature), the Coordination state is used to synchronize multiple pipeline instances:

Unavailable → Coordination → Initializing → ...

During coordination, the pipeline instances establish communication and agree on work distribution before proceeding to initialization.

What’s Next

• Pipeline Configuration: Learn about all available configuration options
• Fault Tolerance: Understand checkpointing and recovery in detail
• Transactions: Use transactions for atomic batch ingestion