Retry Policies and Error Handling

Failure is a first-class concept

Real automations encounter bad data and transient hiccups. StretchAutomate treats failure as something to observe and recover from, not hide. Every run and every step carries a status, an attempt count, and — where a retry is scheduled — a next‑retry time, all visible in the Run ledger. This article explains those states and gives you a playbook for handling them.

Run states and step states

A run finalizes as one of:

• simulated — a clean dry run; nothing to recover.
• partial — some steps didn't fully complete. Two common causes: a step hit an unresolved reference (a data‑mapping problem), or, in a live run, action steps are queued (pending) for dispatch.
• failed — the run hit an error it couldn't continue past.

Each step in the trace carries its own status — succeeded, skipped, simulated, pending, or failed — plus its attempt count and any error message. The ledger's list view also summarizes, per run, a blocked count (skipped + failed steps), a retry count (total attempts across steps), and the next retry time if any step is scheduled to retry.

How retries work

When a step fails in a way that is worth retrying, StretchAutomate's engine computes a retry policy: given the step's attempt count and the policy, it decides whether to retry and, if so, when (the next‑retry time). Each retry increments the step's attempt counter, and the ledger surfaces the earliest scheduled next retry across the run so you know when the platform will try again. Retries let transient problems resolve themselves without you re‑running the whole workflow by hand.

A diagnosis playbook

When the dashboard flags failed or partial runs, work the ledger top‑down:

1. Open the newest failed/partial run. Note the overall status and the blocked count.
2. Find the first non‑succeeded step in the trace. Skips propagate downward, so the first skipped or failed step is usually the root cause; everything after it may just be collateral.
3. Read the step's status and error:
- failed with "unresolved refs" → a data‑mapping problem. The error names the exact reference. Fix the field path or add the missing dependency (see Mapping Data Between Steps).
- skipped ("filter did not pass") → a filter gated this branch. Intended? Leave it. Not intended? Adjust the filter rule or the data it reads.
- skipped ("upstream step skipped") → collateral from an earlier skip. Fix the upstream step.
- pending → an action queued for live dispatch. Not an error; it completes when dispatch runs.
4. Fix, then re‑simulate. Prove the corrected run finishes clean in simulate mode before running it live again.
5. Watch the retry columns. If a step is scheduled for a next retry, you may only need to wait — but recurring retries on the same step point to a persistent problem to fix at the source.

Realistic example

A nightly Paid invoices → thank customers workflow starts finalizing as partial. In the ledger, the newest run's first non‑succeeded step is thank_email, failed, error "unresolved refs: trigger.customer_email." The trigger actually provides trigger.email, not customer_email — a mapping typo introduced in the last edit. The operator corrects the token, re‑simulates with a sample paid‑invoice payload (clean this time), and re‑publishes. The next live run finalizes without blocked steps.

Tips

• The first non‑succeeded step is the story. Downstream skips are usually just propagation.
• Unresolved references are data problems, not engine problems — the fix is almost always a mapping or a missing dependency.
• Use the retry count in the ledger to spot a step that keeps retrying — that's a source‑level issue to fix, not wait out.
• Always re‑simulate after a fix before going live; simulate has no side effects and confirms the reference now resolves.

Troubleshooting

Runs are partial in live mode but simulate cleanly. In live mode, action steps are queued (pending) for dispatch, which finalizes the run as partial until dispatch completes. Confirm the pending steps aren't actually failed.

A step keeps retrying and never succeeds. Retries handle transient issues, not permanent ones. Read the error, fix the underlying cause (bad reference, missing connection), and re‑run.

"Run not found" when opening a run. The run id/key is wrong or belongs to another organization. On the workspace surface you only see your own org's runs — open the run from your own Run ledger list.