Exit codes
0 success, 1 validation, 2 parse, 3 runtime.
Cannectors uses a small, stable set of exit codes so CI and process supervisors can branch on them.
| Code | Meaning | Emitted by |
|---|---|---|
| 0 | Success — pipeline valid, or run completed cleanly. | validate, run, version |
| 1 | Validation errors — schema check failed. | validate, run |
| 2 | Parse error — the file is not valid YAML/JSON. | validate, run |
| 3 | Runtime error — a stage failed past its onError policy. | run only |
When each code is set
0 — success
validate: schema passed.run: the pipeline ran to completion (one-shot) or was stopped via SIGINT/SIGTERM after gracefully draining in-flight work.version: always.
1 — validation error
The YAML/JSON parses, but doesn't match the pipeline schema. The error message names the offending module and field.
✗ filters[1] (mapping): mappings is requiredThis is the code that should fail a CI gate.
2 — parse error
The file isn't valid YAML/JSON at all — indentation broken, unclosed quote, invalid escape. The error names the line and column.
✗ parse error: line 14:7 — could not find expected ':'Treat the same as code 1 in CI.
3 — runtime error
Only run emits this. It means the runtime started executing,
something failed past the configured onError policy, and the
pipeline aborted. Examples:
- Output endpoint returns a non-retryable 4xx after the
retryblock is exhausted. - A
scriptfilter throws andonErrorisfail(the default). - Database connection drops mid-transaction.
The log carries the root cause and the record index that triggered the failure. Process supervisors should treat code 3 as a normal "restart me" signal — there's nothing wrong with the YAML, just a transient external problem.
Branching in shell
cannectors run pipeline.yaml
case $? in
0) echo "done" ;;
1|2) echo "fix the YAML and retry" ;;
3) echo "transient runtime error — will be restarted" ;;
esac