Troubleshooting
Breyta flow troubleshooting guide for push, bindings, wait, and runtime step failures.
Quick Answer
Triage in this order: validate flow syntax, confirm flow exists in target source, isolate failing step, verify bindings/secrets, then rerun full workflow.
Triage Matrix
| Failure mode | Symptoms | Checks | Next action |
|---|---|---|---|
| Push fails with EDN parse error | Push fails with parse errors; odd forms in map/bindings. | Run breyta flows paren-check <file>.Verify file has real newlines (not escaped \n outside strings).Re-apply minimal edit and push again. | Fix delimiter/EDN structure first, then retry push. |
| Flow not found during configuration | flows configure or run commands fail with flow-not-found. | Run breyta flows show <slug>.If missing, push/create flow first. Continue only after show succeeds. | Re-establish workspace flow state in API mode before configuring/running. |
| Step fails in full run | Workflow fails but root cause is unclear. | Run failed step in isolation (breyta steps run ...).For function refs include --flow <slug>.Add/verify retries only for transient failures. | Rerun full workflow only after isolated step succeeds. |
| Wait never resolves | Runs remain in wait longer than expected. | Confirm explicit :timeout.Ensure payload has identifiers needed for signaling. Branch timeout path explicitly. | Make wait deterministic (:key, :timeout, timeout branch). |
| Configuration/secret errors at runtime | Unauthorized responses; missing secret or connection errors. | Ensure all required slots are configured (breyta flows configure <slug> --set ...).Verify installation target settings when using --target live or --installation-id. | Reapply configuration, then rerun with breyta flows run <slug> --wait. |
Connection Reuse Check (Avoid Duplicates)
| Step | Command / check |
|---|---|
| 1 | Run breyta connections list. |
| 2 | Confirm :requires slots point to existing workspace connections. |
| 3 | Create new connection only when no existing one matches provider/environment/auth. |
Frequently Asked Questions
Why do configure commands fail with "flow not found"?
Because the flow was not pushed successfully; verify with breyta flows show <slug> first.
When should I run full workflow again?
Only after the failing step passes in isolation and required bindings are confirmed.