Failure-Mode Cookbook
Practical failure signatures and fixes for advanced flow configs (child orchestration, ref loading, waits, webhook auth, notifications).
Quick Answer
Use this as a triage map: match the error signature, apply the canonical fix, and rerun at step scope before full flow reruns.
Child Flow And Profile Context Failures
| Error signature | Why it happens | Canonical fix |
|---|
no installation or live target context | Child flow needs bound :requires context, but the parent run did not carry an installation/live target context. | Same-app children inherit context from a linked public install. For other child calls, invoke with --target live, :installation-id, or :profile-id; use KV handoff when target propagation is unclear. |
Ref-Load And Size Failures
| Error signature | Why it happens | Canonical fix |
|---|
Blob reference too large for ... | Ref exceeds context-specific load cap. | Keep LLM refs compact; keep code refs under limits; stream/pre-split payloads for HTTP body refs. |
Code step :input too large | Total function input exceeds code input cap. | Pass only required fields; move heavy transforms to DB/warehouse/external compute; orchestrate smaller batches. |
Wait/Approval Failures
| Error signature | Why it happens | Canonical fix |
|---|
Wait timeout exceeds maximum | Configured timeout is above allowed max. | Use shorter bounded waits ("2h", "1d"); chain waits for long multi-stage processes. |
| Runs repeatedly timing out at wait | Completion signal is missing or timeout policy is weak. | Ensure deterministic wait key/signal path; set explicit :on-timeout; include operator context in :notify. |
Webhook/Auth Failures
| Error signature | Why it happens | Canonical fix |
|---|
Webhook authentication required | Webhook interface is missing valid auth config. | Set interface auth (:interfaces {:webhook [{:auth {:type ...}}]}); bind required secret/public-key refs in the target bindings. Older webhook definitions remain compatibility-only. |
Signature authentication requires raw request body | Signature verification cannot run on parsed-only payload. | Preserve raw request body in ingress; keep signature/timestamp header mapping correct. |
Webhook replay detected | Duplicate delivery/signature within replay window. | Use provider idempotency keys/event IDs; ensure retries send unique delivery metadata where possible. |
Notification Failures
| Error signature | Why it happens | Canonical fix |
|---|
:channels is required for notify step | Notify step executed without channels payload. | Provide at least one :http channel; validate notify payload in step isolation before full run. |
partial channel delivery (:all-sent? false) | One or more channels failed while others succeeded. | Inspect per-channel result map; add retry/compensation around notify; keep payload bounded and template variables explicit. |
Operational Triage Loop
| Step | Action |
|---|
| 1 | Isolate failing step with breyta steps run when possible. |
| 2 | Apply minimal config fix from this cookbook. |
| 3 | Rerun step in isolation. |
| 4 | Rerun full flow with breyta flows run <slug> --wait. |
Related