Troubleshooting Common Problems

How to use this guide

Find your symptom below, read the cause, and follow the fix. Most StretchAutomate problems fall into a handful of categories: the engine being off, data‑mapping mistakes, filter/skip behavior, structural graph errors, connection issues, and organization scoping. When in doubt, open the affected run in the Run ledger — the per‑step trace names the exact step and reason.

"StretchAutomate engine is not enabled"

Cause: Running a workflow, publishing, ad‑hoc step evaluation, and retry computation all require the compute engine, which is gated and off by default.

Fix: Ask your administrator to enable the StretchAutomate engine. You can still build, edit, and read validation/plan snapshots without it — but live validation, publishing, and runs need it on. Administrators can confirm status from the engine status view; if it reports a health error, the engine is enabled but the compute service is unreachable and needs attention at the deployment level.

A step failed with "unresolved refs"

Cause: A step's input references a value that wasn't in the run context — either a field the trigger payload didn't contain, or a step that hadn't run yet.

Fix: Open the run; the failed step lists the exact unresolved reference (e.g. trigger.customer_email). Either correct the field path to match the real payload, or add a depends_on so the producing step runs first. Then re‑simulate with a realistic payload to confirm it resolves. Unresolved references also turn the whole run partial, so fixing them clears the dashboard's failed count.

Steps were skipped that I expected to run

Cause: A filter upstream did not pass. When a filter fails, it is skipped and every dependent step is skipped too (reason "upstream step skipped").

Fix: In the ledger, find the first skipped step — it's the filter (or an earlier skip). Check the filter's rules and the data they read. If the skip was intended, no action needed. If not, adjust the rule or ensure the step you wanted unconditional depends on the trigger, not on the filter.

"Workflow has no steps to run"

Cause: You tried to run a workflow that has no steps.

Fix: Add at least one step, then run.

"Workflow graph is invalid; validate before running" / Publish rejected

Cause: The graph failed validation — commonly a step depends on a step key that doesn't exist, or there's a dependency cycle. Publishing enforces validation and won't activate an invalid workflow.

Fix: Open Validate & Plan, read the errors, and fix the cited references or remove the cycle. Re‑validate until valid, then run or publish.

Validation errors on save: name, status, or trigger type

• "A workflow name is required." Enter a name.
• "Workflow status is invalid." Status must be one of draft, active, paused, archived.
• "Workflow trigger type is invalid." Trigger type must be one of manual, webhook, schedule, app_event.
• "A step_key is required." Every step needs a unique key.

An action never takes effect

Cause: Either you ran in simulate mode (no real side effects), the workflow isn't Active, or the connector lacks an active connection.

Fix: Confirm you're running live, the workflow is Active, and the Connections tab shows an active connection for that connector. Remember that live action steps are queued (pending) for dispatch, so there can be a short delay before the effect lands.

"connector and name are required" when creating a connection

Cause: A connection needs both a connector and a name.

Fix: Provide both and save. Give it a purpose‑based name so you can tell multiple connections apart.

"Run not found" or "Workflow not found"

Cause: The id/key is wrong, or the record belongs to a different organization. On the workspace surface you only see your own org's data.

Fix: Open the item from your own Workflows or Run ledger list rather than pasting an id. If you're an administrator, confirm you're on the right surface.

A trigger never fires

Cause: The workflow isn't Active, or the chosen App event simply hasn't occurred.

Fix: Set the workflow to Active. Test the logic first with a Manual trigger and a sample payload to prove the steps work, then rely on the real event.

Tips for faster diagnosis

• Start at the Dashboard to notice failed/partial spikes, then drill into the Run ledger.
• The first non‑succeeded step in a trace is almost always the root cause; downstream skips are collateral.
• Simulate after every fix — it's side‑effect‑free and confirms the correction before you go live.
• Keep realistic sample payloads handy so simulations exercise the same references production will.