All docs

Troubleshooting

Why an automation didn't run.

Updated . 4 min read.

Automation failures usually fall into one of three buckets: the run was never created, the run stopped on purpose, or a step failed while executing. Start with the run list for the automation, then open the individual run to inspect each recorded step.

Run was not created

Check these first:

  • The automation is active.
  • The trigger matches the event you expect.
  • The automation belongs to the same form or survey that received the submission.
  • The submission was not filtered out before the trigger point.
  • The team has not exceeded its monthly automation run quota.

For submission workflows, remember that submission.created is intended for accepted submissions. Spam-only workflows should use submission.marked_spam when you want to react after a row moves to spam.

Run stopped early

A stopped run is not always a failure. A condition step that does not match halts gracefully and marks the run successful. A branch step can also stop the pipeline when the selected true_step_id or false_step_id is empty.

Open the run's step log and look for:

  • matched: false on a condition step.
  • branch: true or branch: false with an empty next_step_id.
  • A cursor position that never reached the step you expected.

If the wrong branch was chosen, compare the rule field names with the actual submission payload. Field names are case-sensitive and must match the stored payload key, not the label shown to the respondent.

Step failed

The run row's error column contains the failure reason for the step that stopped execution. Common causes include:

  • send_email received an invalid or empty recipient.
  • send_webhook or http_request could not reach the destination URL.
  • integration_driver is missing provider credentials or a required URL.
  • ai_classify was blocked by quota or unavailable AI credits.
  • update_field points to a field that is not present in the submission payload.

Set continue_on_failure: true on a non-critical step when later steps should still run. Leave it off for steps that must succeed before the workflow can safely continue, such as notifying an owner before marking a submission as processed.

Delays and queued work

A delay step records the delay and resumes the run automatically once the wait elapses. If a delayed run does not resume within a few minutes of its scheduled time, check the run's step log on the runs page - the run stays resumable because its position is stored with the run, and you can replay it at any point. If runs are stuck across multiple automations, check status.formspring.io or contact support.

Replay a run

Replay from the runs page or call:

txt
/api/v1/forms/{form}/automations/{id}/runs/{run}/replay

Replay creates a fresh execution attempt for the same automation context. Use it after fixing credentials, correcting a destination URL, or making a downstream service available again. Avoid replaying before you know whether the failed action is idempotent; a repeated webhook or email can create duplicate external work.

Resume a run

A run that failed, that is waiting for someone to check it, or that a limit paused can be put back on the queue at the step that stopped it. Steps that already went out are not repeated. Use Resume on the run page, or:

txt
POST /api/v1/forms/{form}/automations/{id}/runs/{run}/resume

For a run that needs review, send resolution: mark_sent when the provider confirmed the request arrived, or retry to send it again (which may deliver it twice, so check with the provider first). A run that is not in one of those states is refused with 422, and a repeated Idempotency-Key answers what the first call did, so an agent that retries a timed-out request never queues the run twice. Agents use the resume_automation_run tool.

Test with a real case

In the test dialog choose Use data from a past run to test with what a real run started with. Emails, phone numbers, names and addresses are masked and secrets are removed before the data reaches you, and the test never sends, requests or saves anything. Over the API, GET .../automations/{id}/test-inputs lists the runs you can choose and POST .../automations/{id}/test takes from_run_id; agents use list_automation_test_inputs and test_automation.

Debug checklist

  1. Confirm the trigger and automation active state.
  2. Open the latest run and read the step log from top to bottom.
  3. Compare condition fields against the actual submission payload keys.
  4. Inspect destination credentials and URLs for failed action steps.
  5. Replay only after the cause is fixed.