Debugging a Failing Step

When an automation run fails, Chase Agents gives you step-level visibility into exactly what went wrong. This guide walks through the debugging process from identifying the failed step to fixing and verifying the repair.

Step 1: Find the Failed Run in Workflow History

Navigate to Workflow History from the sidebar. Find the failed run. It will be marked with a failure indicator. Click the run to expand it and see the step-by-step execution log. Steps that completed successfully are marked green. The step that failed is marked red. Steps that did not execute because a prior step failed are marked grey.

Step 2: Read the Error Message

Click the failed step to see its error message. For connection steps, the error usually comes from the external API and includes an HTTP status code and a message. Common errors: 401 means the connection credentials are invalid or expired; 403 means the API key does not have permission for this operation; 404 means the resource being requested does not exist; 429 means the external API's rate limit was hit; 500 means the external service had an internal error.

Step 3: Examine the Step Inputs

The step log shows what inputs the step received. For a run_sandboxed_code step, this is the data available to the script. For a connection tool step, this is the parameters passed to the tool. Verify that the inputs match what the step expected. A common cause of failures is a prior step returning data in a different shape than expected, causing a reference like dataPrev.id to be undefined.

Step 4: Fix the Step in the Visual Editor

Once you understand the cause of the failure, open the automation in the visual editor and fix the failing step. For credential errors, update the connection configuration. For data reference errors, correct the field path that references prior step data. For code errors in run_sandboxed_code steps, fix the Python logic. Save the automation after making changes.

Step 5: Test the Fix

After fixing the step, run the automation manually using the same type of input data that caused the failure. Watch the new run in Workflow History and verify the previously failing step now succeeds. Check the outputs of the fixed step match your expectations before re-enabling the automation on its normal schedule.

Common Step Failure Patterns

The most common step failure patterns are: credential expiry (OAuth tokens need to be refreshed or re-authorized, API keys have been rotated on the service side), API schema changes (an external service changed its request or response format), null reference errors (a prior step returned empty data and the current step tried to access a field on it), and rate limiting from external services (the automation runs too frequently for the external API's limits).

Using Auto-Fix for Debugging

If the automation's error handling mode is set to ai, the platform may have already attempted an auto-fix when the step failed. Check Workflow History for any auto-fix attempts. If auto-fix repaired the step and the run continued, the fix is visible in the step history. If auto-fix was attempted but failed, the error message for the auto-fix attempt gives additional diagnostic information about why the repair did not work.

Getting Help

If you cannot determine the cause of the failure from the error message and step inputs, post in the Discord with the error message text, the step type, and the outputs of the preceding step. This context is usually enough to diagnose the problem quickly.