Troubleshooting & FAQ

Flow execution failures

Use the Logs page to find the failed step, inspect its data, and verify a fix.

Identify a failed execution

Use the Logs filters and execution details to locate the failure. Follow these steps:

  1. Open Logs.
  2. Set Status to Failed.
  3. Select the failed execution.
  4. In Timeline, select the step with an error.
  5. In Step inspector, review the step’s input, output, configuration, and error details.

If a value is missing from the Step inspector, check whether verbose logging was enabled when the execution ran. Logs might not contain full outputs, token counts, or costs when verbose logging is off.

Diagnose common failures

Match the error to its step type, then apply the relevant check.

Invalid JSON

If a request body or Run Code step reports invalid JSON, inspect the string that the step parses and the body that the HTTP step sends. Validate the JSON syntax, quote string values, and remove trailing commas. In a Run Code step, use JSON.parse to read a JSON string and JSON.stringify to serialize an object.

Missing input

When a required input is missing, compare the execution input with the fields that the Flow references. Check the spelling of each outputVariable. Confirm that the step that produces it runs before the reference. Add a validation step for values that must exist.

Use the following Run Code script to validate a required input:

1if (!input.customer_id) {
2  throw new Error('Customer ID is required')
3}
4
5return { validated: true }

Replace customer_id with the required input field. Choose Stop on error when a missing value must stop the Flow.

HTTP request failure

If Fetch URL or Make API Call returns an HTTP error, inspect the status, URL, method, headers, request body, and response format. Check these settings:

  • Verify that the endpoint and method match the external API.
  • Verify that authentication headers use the required secret or API key.
  • Confirm that the response format matches the value that the next step expects.
  • For an HTTP 500 response, review the external service response and retry according to its retry rules.
  • When the service limits request frequency, add a Wait Until step between requests.

Choose an Error handling mode after a request fails: Continue on error, Stop on error, or Use fallbacks.

Record not found

Get Record returns one Record and fails when no Record matches. List Records returns an array. With the default On empty value of Succeed, List Records returns [] when no Record matches. Set On empty to Fail when an empty result must fail the step.

Check these values when a Record lookup fails:

  • Verify the Record ID, Record type, Record Name, filter, and lookup value.
  • Use Get Record when no match must fail the Flow.
  • Use List Records when no match is expected. Then check {{RECORD_MATCHES.length}} > 0 in a Conditional Logic step.

Replace RECORD_MATCHES with the Output variable name for the List Records step.

Run Code error

If Run Code reports a JavaScript error such as ReferenceError, check variable spelling, variable scope, and null or undefined values. Declare local variables with const or let, and return a value from the script.

To test a top-level Run Code step with data from a previous execution, run the Flow once. Open the step’s action menu, then choose Test with last run.

Timeout

The default step timeout is 5 minutes, and the default Flow timeout is 15 minutes. Compare the failed step’s duration with its timeout value in Logs. Reduce the work in the step or change its timeout when the work needs more time.

Debug and verify a fix

Use a test run to reproduce the failure with controlled input. Follow these steps:

  1. In the Flow editor toolbar, click Run flow.
  2. In the Run Flow sheet, choose Test.
  3. Enter the input values for the Flow.
  4. To include outputs from hidden steps, open the execution mode menu and choose Run in debug mode.
  5. Click Run Flow.
  6. Review each step’s input, output, status, and execution time when available.

To inspect intermediate values, add a Run Code step that returns the values you want to review. The execution results show the returned output.

After you fix the problem, save the Flow and run the test again. Publish the Flow after you verify the fix when dispatched executions must use the change.

Prevent repeat failures

Use these practices to make Flow inputs and outputs explicit:

  • Validate required inputs at the start of the Flow.
  • Check for null and undefined before you access properties.
  • Check HTTP status codes and expected response fields before you use response data.
  • Configure step-level error handling for failures that the Flow can handle.
  • Test empty inputs, null values, invalid data, API failures, and missing Records.

Handle expected errors

Some scenarios represent valid branches instead of defects. Handle them explicitly:

  • For invalid user input, return a clear validation message.
  • For a temporary external API failure, retry or queue the work according to the service contract.
  • For a missing Record, use List Records with On empty set to Succeed. Return a default or create a Record when appropriate.

When a step can fail without ending the Flow, choose Continue on error. Handle its missing or default output in a later step.

Next steps

Continue with these guides: