Skip to content
Factflow

Pipeline configuration

Pipelines are YAML files. The server stores them as configs; you run executions against those configs. This guide covers the day-to-day operator loop.

Validate before submitting

Section titled “Validate before submitting”

Always validate locally first. Catches errors without touching the server:

Terminal window
factflow config validate backend/config/pipelines/my-pipeline.yaml

Exit 0 on success. Non-zero with stable error codes (E001–E501) on failure.

For JSON output (scriptable):

Terminal window
factflow config validate my-pipeline.yaml --output json

Want a batch validation of every shipped YAML?

Terminal window
factflow config validate backend/config/pipelines/

Create a config

Section titled “Create a config”
Terminal window
factflow config create -f my-pipeline.yaml

Returns the stored config record with an id. That id is what you pass to factflow config run.

From stdin:

Terminal window
cat my-pipeline.yaml | factflow config create -f -

List and inspect

Section titled “List and inspect”
Terminal window
factflow config list
factflow config list --active
factflow config list --inactive


factflow config get CONFIG_ID

get returns the full YAML plus metadata (version, source type, hash).

Edit

Section titled “Edit”

Configs are versioned. Editing increments the version. In-flight executions are unaffected (they run against their snapshot):

Terminal window
factflow config edit CONFIG_ID -f my-pipeline-v2.yaml

Run an execution

Section titled “Run an execution”
Terminal window
factflow config run CONFIG_ID

Returns an execution id. The pipeline starts immediately.

Delete

Section titled “Delete”
Terminal window
factflow config delete CONFIG_ID

Returns 204 on success. Doesn’t affect executions already run against the config (their snapshots are independent).

Startup validation

Section titled “Startup validation”

On server startup, every shipped YAML under backend/config/pipelines/ is validated. Default is strict — a broken YAML aborts startup. To run warn-only (for rapid iteration):

Terminal window
FACTFLOW_CONFIG_VALIDATOR_STRICT=0 uv run python -m factflow_server serve --embedded

Strict is the production default. Don’t flip it off permanently.

Error codes

Section titled “Error codes”

The validator uses a stable taxonomy:

  • E001–E099 — YAML parsing errors
  • E100–E199 — schema violations (missing fields, wrong types)
  • E200–E299 — route errors (unknown queue, bad concurrency)
  • E300–E399 — adapter errors (unknown type, invalid config)
  • E400–E499 — init message errors (missing route, bad payload)
  • E500–E501 — global errors
  • W501–W503 — warnings (deprecated fields, suboptimal settings)

Full table in the pipeline YAML reference.

Section titled “Related”