Debugging failures

A systematic approach to "my workflow failed, now what?"

The five-minute investigation

1. Find the run. In the editor, open the executions dropdown and click the failed run. Or find it in Logs with the Failed chip and click Go to Workflow.
2. Find the red node. The canvas colours each node by its status in that run. In execution detail, the state card names the node: "Workflow failed at: ".
3. Read the error. Click the red node. Its output holds the error message. See Reading node output.
4. Check the input. Click the node before it. Is its output what the failing node expected? If not, the problem is upstream.
5. Fix and run again. Edit the workflow, press Back to edit if a past run is loaded, then rerun the failed run or test the node.

Reading node output

Click a node while a run is loaded to open its inspector. It has three tabs: Settings, Schema and JSON.

• The status line reads "Latest node output" for the most recent run, or "Past run loaded" when you picked a run from the list. It shows the version, such as V12, and Success or Failed.
• Schema shows the shape of the output: field names and types.
• JSON shows the values. Use Expand all and Collapse all to open or close the tree, and Copy JSON to copy it.
• Long values wrap inside their cell. A very long value is cut off with Show more (N characters left). Click it to read the rest.
• Click a value to copy it.
• Files a node produced have a Download button.
• Loops: a node inside a loop has an Iteration N of M picker. It opens on the latest iteration. Pick another to see that pass.

An empty inspector reads "Run the flow to see output data".

From the JSON tab you can also Edit JSON and Pin Data to fix a node's output while you test. See Pinning data.

Common errors and what they mean

Timeout

The node ran past the Timeout (ms) set in its Node Settings. The node and the run show as Failed.

Fix:

• Raise the node's timeout, or clear it for no limit.
• Set Error Mode to Retry with Backoff.
• Find out why the service is slow.

Network error or connection refused

A DNS failure, a brief network problem, or the service is down.

Fix:

• Set Error Mode to Retry with Backoff with 1 to 3 retries.
• For important calls, wire the node's error port to a fallback branch.

Authentication errors (401, 403)

The credential has expired, been revoked, lacks a scope, or belongs to the wrong account.

Fix:

• Test the credential under Settings → Integrations.
• Reconnect it if it has expired.
• Check the scopes the connector needs in the connector catalog.

Rate limit (429)

You are calling the service faster than your quota allows.

Fix:

• Add a Delay node, or use the API Pagination & Rate Limit node.
• Cache responses you fetch repeatedly.
• Run the workflow less often.

Validation error

A field did not match what the node expected. Either the node's settings are wrong, or the incoming data is not the shape you expected.

Fix:

• Read the message. It usually names the field.
• Add a Schema Validator Guard earlier to catch bad data before it reaches this node.

[EXPR-ERROR: ...]

An expression could not be resolved. See Debugging expressions.

4xx from the service

A business error, such as "not found" or an invalid state change. Read the response body in the node's output. Most services explain the problem there.

5xx from the service

The service had a problem on its side. Retry. If it keeps failing, contact the service.

"The worker running this execution stopped responding"

The worker running the run was restarted or crashed. Flero closed the run as Failed and did not re-run it. Check whether any node already took effect, then use Rerun.

When the problem is your data

Sometimes the workflow is right and the data is not. Pick the guard that fits:

• Known, stable shape: validate it early with a Schema Validator Guard.
• Optional fields that are sometimes missing: set defaults with Data Transform or a Code node.
• Values that are sometimes the wrong type: convert them with Data Transform.

Fix and try again

After a fix, rerun the failed run from the editor's executions list. The rerun uses the same trigger data, so you can check the fix without waiting for a new trigger.

For a longer round of changes:

1. Load the failed run, then hover it and click Load to Editor. You stay in edit mode with that run's outputs in the inspector.
2. Pin the trigger's output so every test uses the same input. See Pinning data.
3. Test the failing node until it works.

When you cannot reproduce it

Some failures happen once and never again: a network blip, a race, a brief auth problem. To rule out a real issue:

• Check Monitoring. Is the failure rate rising?
• Search Logs for the same error across all workflows. Is it workspace-wide?
• Rerun a few times. Does it fail every time?

If it is a one-off, note the execution ID and move on. If it comes back, dig deeper.

When the run is stuck, not failed

See Rerun, stop & pause.

Logging strategically

Before things go wrong, add Log nodes at key points with level info. When something fails, those logs are the first place to look.

Message: Fetched users for tenant {{ $trigger.payload.tenantId }}: {{ $node["Fetch users"].output.response.body }}
Level:   info

Tips & gotchas

• Read the whole error message, not just its type. It often names the field.
• One failure can hide another. Nodes after a failure do not run, so a second problem may appear only after you fix the first.
• Sandbox mode lets you reproduce failures that involve outside services without real side effects. Remember that a rerun always runs live.
• Do not retry non-idempotent operations like charges or emails. Use an idempotency key, or handle the failure on the error port.

Related

• Execution detail
• Retries & error handling
• Rerun, stop & pause
• Debugging expressions
• Sandbox mode

Found something out of date? This page lives in the Flero docs content set.