Debugging Workflows

When a workflow fails, the execution log tells you exactly which step failed, what input it received, and what error occurred. This guide covers the debugging process and common failure patterns.

Debugging Process

1. Find the Failed Step

Open the run in the visual builder or query the Runs API. The failed step has status: "failed" with an error message:

{
  "id": "create-invoice",
  "status": "failed",
  "error": {
    "code": "INTEGRATION_ERROR",
    "message": "QuickBooks: Customer not found for ID cus_missing",
    "step": "create-invoice"
  }
}

2. Check the Step Input

The input field shows exactly what data reached the step. Common issues:

• Template variables resolved to null or undefined
• Upstream step output was in an unexpected format
• Data type mismatch (string vs number)

3. Check Upstream Steps

Walk backward through the execution log. If a Transform step produced unexpected output, the issue is in the transform mapping, not the downstream step that consumed it.

4. Fix and Re-run

After identifying the issue, update the workflow and run it again with the same input.

Common Error Patterns

Template Variable Errors

Symptom: Step receives null or undefined instead of expected data.

Cause: The template variable references a step that does not exist, or the output field name is wrong.

// Wrong: step name mismatch
"to": "{{steps.fetchCustomer.output.email}}"

// Correct: matches the actual step ID
"to": "{{steps.fetch-customer.output.email}}"

Connection Expired

Symptom: Integration step fails with 401 Unauthorized or Token expired.

Fix: Re-authenticate the connection in the Connections panel. OAuth tokens expire periodically and need refreshing.

Rate Limiting

Symptom: Integration step fails with 429 Too Many Requests.

Fix: Add a Wait block before the integration step, or reduce the concurrency of parallel loops. Most APIs allow 100-300 requests per minute.

Timeout

Symptom: Step fails with TIMEOUT error.

Fix: Increase the step timeout in the configuration. For long-running operations (browser automation, large data extracts), set timeouts of 60-120 seconds.

JSON Parse Error

Symptom: Agent block returns text that cannot be parsed as JSON.

Fix: Add an output schema to the Agent block. This constrains the model to return valid JSON matching your schema.

Missing Required Fields

Symptom: Integration step fails with 400 Bad Request -- required field missing.

Fix: Check the step input in the execution log. Ensure all required fields are populated via template variables or static configuration.

Debugging Agent Blocks

Agent blocks can be tricky because the output depends on the AI model. Common debugging steps:

1. Check the system prompt -- Is it specific enough? Vague prompts lead to inconsistent output.
2. Check the input data -- Did the upstream block pass the expected content?
3. Check the output schema -- Is it valid JSON Schema? Does it match what you expect?
4. Lower the temperature -- Set to 0 for deterministic output during debugging.
5. Check token limits -- If output is truncated, increase max tokens.

Debugging Stagehand (Browser) Blocks

Browser automation failures are often caused by page changes or timing issues:

1. Use screenshots -- Add a stagehand.screenshot step before and after the failing action.
2. Increase timeouts -- Set timeoutMs to 60000 or higher for slow-loading pages.
3. Check the instruction -- Be specific: "Click the blue Download PDF button" is better than "Click download."
4. Enable agent fallback -- Set agentFallback: true so the system switches to autonomous agent mode when a simple action fails.

Using the Run Inspector

The visual builder includes a run inspector that shows:

• Step timeline -- Visual representation of step execution order and duration
• Input/Output panels -- Raw JSON for each step's input and output
• Error details -- Full error message, stack trace (when available), and retry history
• Template resolution -- Shows how template variables were resolved

Best Practices

• Start small. Test workflows with a single step before building the full chain. Verify each step produces the expected output.

• Use the Transform block for data inspection. Add a Transform block to log intermediate data during development. Remove it before deploying.

• Set up error notifications. Add a Condition block that checks for failures and sends a Slack or email alert.

• Keep workflows focused. A workflow that does one thing well is easier to debug than a workflow that does ten things.