> ## Documentation Index
> Fetch the complete documentation index at: https://learn.workflow.dog/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot workflow runs

> Find the cause of failed runs and node errors, fix the current workflow, and test safely.

Start with the run's status and error location. A run-level **Failed** status
and a node error inside a **Completed** run describe different problems and
need different fixes.

## Diagnose the run

<Steps>
  <Step title="Open the run">
    Open **Workflow Runs** from the project, or open **Run History** inside the
    workflow editor and select the affected run.
  </Step>

  <Step title="Classify the failure">
    If the run is **Failed**, read the status tooltip for its run-level reason. If
    it is **Completed** with an amber warning, inspect the nodes that stored
    errors.
  </Step>

  <Step title="Switch to Snapshot">
    Use **Snapshot (Read-Only)** to inspect the graph that actually executed. Do
    not assume the current canvas still matches an older run.
  </Step>

  <Step title="Inspect node data">
    Open the failed node's error and review upstream outputs. Confirm the input
    shape, account, identifiers, and values the node received.
  </Step>

  <Step title="Fix the current workflow">
    Switch to **Overlay** or deselect the run, make the correction, and wait until
    the editor says **Saved**.
  </Step>

  <Step title="Test with the saved payload">
    Choose **Re-run** to use the same trigger data with the current saved graph,
    or send a new representative trigger event.
  </Step>
</Steps>

## Run-level failures

Run-level failures occur before node processing begins or when the workflow
runner itself cannot complete its job.

| Message or code                                                             | What to check                                                        |
| --------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| **The workflow is paused.**                                                 | Enable the workflow, then create a new run.                          |
| **The project is out of workflow runs and isn't set up for usage billing.** | Add credits or enable pay-as-you-go billing.                         |
| **The payment is invalid.**                                                 | Resolve the project's payment issue in the billing portal.           |
| **The worker encountered an error.**                                        | Re-run once; if it repeats, preserve the run ID and contact support. |

A failed eligibility check is not retried automatically. Fix the cause, then
send a new event or choose **Re-run**.

<Note>
  A manual re-run goes through the same Live/Paused and billing checks as an
  external trigger event.
</Note>

## Node errors in a Completed run

WorkflowDog records node errors independently and continues settling the graph.
The overall run can reach **Completed** even when one or more nodes failed.

Check:

* The failed node's exact stored message.
* Whether its connected inputs produced values.
* Whether a required static input is empty.
* Whether an integration account is healthy and has the required permission.
* Whether an external identifier still exists and belongs to that account.
* Whether the value's type matches what the node accepts.

Downstream nodes may not run when their required input path did not receive a
value from the failed node. Diagnose the earliest error in the path first.

## Inspect the graph that actually ran

<Tabs>
  <Tab title="Snapshot (Read-Only)">
    This is the authoritative historical graph. Use it to confirm the node
    version, connections, static values, disabled nodes, and layout selected
    when the run was queued.
  </Tab>

  <Tab title="Overlay">
    This applies historical results to the current editable graph where IDs
    still match. Use it while implementing a fix, but switch back to Snapshot
    when you need to verify historical structure.
  </Tab>
</Tabs>

If the workflow was deleted, the project can retain a **Deleted Workflow** run
row for usage tracking while its snapshot is no longer available.

## Re-run safely

Re-run copies the old run's trigger payload into a new run. It does not execute
the old graph.

Before re-running:

* Confirm the editor shows **Saved**.
* Confirm the workflow is Live.
* Confirm integration accounts are healthy.
* Consider whether the workflow sends messages, charges payments, creates
  records, or performs another non-idempotent action.
* Check whether the original run partially completed before its node error.

<Warning>
  Re-running can repeat side effects that succeeded in the original run. A node
  error later in the graph does not roll back earlier emails, records, uploads,
  or provider changes.
</Warning>

For risky workflows, temporarily disable side-effect nodes or route the payload
through a test copy before replaying it.

## Integration errors

When an account-backed node errors:

<Steps>
  <Step title="Check account health">
    Open **Integrations** and look for **Needs Reconnecting**.
  </Step>

  <Step title="Reconnect or approve permissions">
    Open the node's account selector. Reauthorize the account if credentials are
    invalid or the node says required permissions are missing.
  </Step>

  <Step title="Confirm the selected account">
    Unhealthy or insufficiently scoped accounts can be cleared automatically from
    the node. Select the healthy account again.
  </Step>

  <Step title="Verify the external resource">
    Confirm IDs, mailbox folders, labels, files, bases, tables, and other
    external resources still exist and are accessible to that account.
  </Step>
</Steps>

For a trigger that stopped delivering events, continue with
[External triggers](/essentials/external-triggers#troubleshooting).

## Variable errors

For project variable problems:

* A missing key returns its default or `null`; it is not a run-level failure.
* Key matching is exact and project-scoped.
* Appending requires the existing value to be a list.
* Parallel append operations can overwrite one another because each operation
  reads and replaces the list.
* Viewers can inspect values but only Editors can clear them.

Inspect the current value under **Project → Variables** before changing the
workflow.

## Scheduled runs

A Scheduled run can be cancelled before execution. Pending and Running runs
cannot be cancelled from the dashboard.

If a delayed run executed after the workflow was paused, it was already
accepted and scheduled before the pause. Pausing does not purge the delayed
queue.

## Save failures

The workflow editor shows **Waiting to save**, **Saving**, **Saved**, or
**Failed to save**.

Do not test a change until the status reaches **Saved**. WorkflowDog prevents
normal navigation while a save is still pending, but a failed save means the
current graph may not be on the server.

A graph containing a circular dependency is rejected during save. Remove the
cycle and wait for a successful save before re-running.

## Escalate a repeatable worker failure

When **The worker encountered an error** repeats with the same saved graph and
payload:

1. Star the representative run.
2. Record the workflow name, run date and time, and run ID from its URL or
   request data.
3. Note whether a new trigger event and a manual re-run fail the same way.
4. Contact WorkflowDog support without copying secrets into the message.

The stored run gives support the execution context; the external account's
credentials should never be pasted into a ticket.

## Quick symptom guide

<AccordionGroup>
  <Accordion title="No run appears at all">
    Verify the external trigger configuration, provider permissions, and
    account health. Then send a new matching event. A trigger filter mismatch
    can prevent WorkflowDog from producing a run.
  </Accordion>

  <Accordion title="The run fails immediately without node activity">
    Read the run-level failure tooltip. Paused and billing failures happen before
    node execution.
  </Accordion>

  <Accordion title="The run is Completed but downstream work is missing">
    Look for an amber warning and inspect the earliest node error. Downstream
    nodes may not receive a signal after an upstream failure.
  </Accordion>

  <Accordion title="The fix works for new events but not Re-run">
    Compare the saved trigger payload with the new event. Re-run preserves the
    old payload, which may reference an external resource that no longer exists
    or contain a value your new event does not.
  </Accordion>
</AccordionGroup>