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.

Error signature	Why it happens	Canonical fix
`requires a flow profile, but no profile-id in context`	Child flow needs bound `:requires` context, but parent execution has no profile context.	Invoke child from profile-aware execution paths; avoid slot-dependent child calls without profile; use KV handoff when profile propagation is unclear.

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.

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`.

Error signature	Why it happens	Canonical fix
`Webhook authentication required`	Webhook trigger is missing valid auth config.	Set trigger auth (`:config {:source :webhook :auth {:type ...}}`); bind required secret/public-key refs in profile bindings.
`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.

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.

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`.