Docs

Troubleshooting

Fix common problems with integrations, workflow runs, human input, browser sessions, and YAML.

Most workflow problems come from a small set of causes. Start with the failed or paused node, then use the sections below.

Integration connection failed

Check:

  • The account is still connected.
  • The provider granted the permissions the workflow needs.
  • Credentials are current.
  • The integration uses the expected account, workspace, board, folder, or project.
  • The workflow node lists the correct integration referenceId.

If the integration has a connection check, run it after changing credentials.

The workflow cannot find a file or record

Check:

  • The file, folder, board, sheet, issue, or record still exists.
  • The connected account has access to it.
  • The workflow is using a stable ID rather than a display name when possible.
  • The task instruction tells the agent what to do if the item is missing.

For documents and folders that workflows use repeatedly, store stable IDs as workflow variables.

A task node gave the wrong answer

Task nodes need clear instructions.

Improve the instruction by saying:

  • What source data to inspect.
  • Which rules to follow.
  • What to return when data is missing.
  • Which fields must be present in the output.
  • What not to infer or invent.

If the task is doing too much, split it into two smaller task nodes.

A code node failed

Code nodes expect structured input.

Check:

  • The upstream node returned the fields the code reads.
  • The code parses every integration response body.
  • The integration path is correct.
  • A non-2xx provider response is handled only if it is an expected branch.
  • The output matches the node dataSchema.

If the code is trying to interpret PDFs, images, documents, or email attachments, move that work into a task node first.

A run is awaiting input

This usually means the run paused for a human node or browser reauthentication.

Open the run in Activity and complete the requested step.

If the human node looks complete but the workflow did not continue, check whether the action returned done: true and enough final state for downstream nodes.

A browser integration needs login

Websites can expire sessions, require MFA, or change their login flow.

When a browser workflow pauses for reauthentication:

  1. Open the requested sign-in flow.
  2. Complete login or MFA.
  3. Return to the run.
  4. Resume or rerun the workflow step.

If this happens often, add an early auth check to the browser step so the workflow pauses before doing other work.

YAML is invalid

Check:

  • There is exactly one YAML document.
  • There are no YAML anchors, aliases, or tags.
  • Node IDs match their keys.
  • Unknown keys have not been added.
  • Root JSON schemas are objects.
  • Required fields match what downstream nodes read.

If the workflow was generated by an agent, validate it before publishing.

A workflow should have paused but did not

Add a human node before the risky action.

Good places to pause:

  • Before sending an email.
  • Before deleting or overwriting data.
  • Before approving money movement.
  • When confidence is low.
  • When required input is missing.

Automation is most useful when it knows where not to be automatic.

Integration Tools