Debugging & Diagnostics

When a workflow fails, A91I provides multiple tools to help you investigate: detailed error messages, node-level inspection, and an AI-powered troubleshooting agent that diagnoses issues automatically.

Finding the Failure

Start by opening the failed execution from the Execution History page. The execution detail page shows which nodes succeeded and which failed. The first failed node is usually the root cause.

1

Open Execution History

Navigate to the Execution History page. Failed executions are marked with a red status badge.
2

Click the execution

Open the execution detail to see the full node-by-node breakdown.
3

Find the red node

Scroll through the node list or look at the timeline. The failed node is highlighted in red.
4

Expand the node details

Click the failed node to see its input data, error message, and execution metadata.

Reading Error Details

Each failed node provides three pieces of information:

Error message
A human-readable description of what went wrong. Examples: "Invalid OAuth token", "Rate limit exceeded", "Required field 'channel' is missing."
Input data
The exact data that was sent to the node when it failed. Compare this with what you expected to identify data-mapping issues.
Execution metadata
Timing information (when the node started and failed), retry count, and the connection used (for action nodes).

AI Troubleshooting Agent

The AI Troubleshooting Agent automates the debugging process. It examines the failed node, its context, and produces a structured diagnosis.

Using the Agent

1

Open the failed execution

Navigate to the execution detail page for a failed run.
2

Click "Diagnose"

The button appears at the top of the page for any failed execution. It sends the failure context to the AI for analysis.
3

Read the diagnosis

The agent returns a structured report with three sections: what happened, why it happened, and how to fix it.

What the Diagnosis Includes

Root cause analysis
A plain-language explanation of the underlying issue — connection expired, API field mismatch, missing required parameter, rate limit exceeded, etc.
Affected nodes
Which nodes were impacted, and whether the failure cascaded to downstream nodes.
Suggested fixes
Specific, actionable steps to resolve the issue. For example: "Reconnect your Gmail connection — the refresh token has expired" or "Add a required 'channel' parameter to the Slack node."

Context-aware

The AI agent sees the full execution context — the workflow structure, node configurations, connection states, input/output data, and the error message. It does not guess; it reasons from the actual data.

Common Issues & Solutions

Authentication Errors

Symptom: Node fails with "401 Unauthorized" or "Invalid token."

  • Check the connection status on the Connections page. If it shows Expired, click Reconnect.
  • Verify that the OAuth app has the required scopes. Some operations require additional permissions.
  • For API-key integrations, confirm the key has not been revoked or regenerated in the service's settings.

Rate Limit Errors

Symptom: Node fails with "429 Too Many Requests."

  • A91I includes built-in rate limiting, but very high-frequency workflows can still hit provider limits.
  • Add delays between iterations in loops that make many API calls.
  • Consider batching — some APIs accept multiple items in a single request.
  • Check the integration's rate limit documentation for current thresholds.

Data Mapping Errors

Symptom: Node receives undefined or unexpected data format.

  • Open the failed node and inspect the input data. Compare it with the expected format.
  • Check the upstream node's output — the field you're referencing may have a different structure than expected.
  • Use the data picker to re-select the correct field path.
  • Add a Transform node before the failing node to normalize the data format.

Connection Failures

Symptom: Node fails with "Connection error" or "ECONNREFUSED."

  • The target service may be temporarily unavailable. Check the service's status page.
  • The circuit breaker may have tripped. If the integration has been failing repeatedly, A91I temporarily stops sending requests. It will recover automatically.
  • For self-hosted services (PostgreSQL, internal APIs), verify the endpoint is reachable from the A91I server.

Timeout Errors

Symptom: Node fails with "Request timeout."

  • The default timeout for HTTP requests is 30 seconds. For long-running API calls, increase the timeout in the node configuration.
  • For Puppeteer (web scraping), complex pages may take longer to load. Increase the page timeout.
  • Consider whether the operation can be broken into smaller requests.

Testing Strategies

Prevent failures before they reach production by testing systematically:

  • Test nodes individually — use the Test button in the configuration panel to validate each node in isolation.
  • Test with real data — use the Test Run feature to execute the full workflow with real API calls and real data.
  • Check edge cases — test with empty arrays, missing fields, and unexpected data formats.
  • Monitor the first few scheduled runs — after activating a workflow, watch the first few automatic executions to catch issues early.
  • Use the AI Suggest feature — the AI can identify potential issues in your configuration before you even run the workflow.