Skip to main content
When a workflow fails, Serval gives you two ways to diagnose the issue: manual inspection through run history, and AI-powered debugging through the workflow builder agent.

​
Diagnose Failures in Run History

Every workflow run logs step-by-step execution details. Start here to understand what went wrong.
1

Open the failed run

Go to Workflows, select the workflow, and click the Runs tab. Click on the failed run to open its details.
2

Find the failed step

The step-by-step breakdown highlights which step failed. Each step shows its status, duration, input, and output.
3

Review the error

Check the error message on the failed step. Common errors include:
  • Authentication errors: Expired or revoked API credentials. Reconnect the application in integrations settings.
  • Not found errors: The target resource (user, group, etc.) does not exist. Verify input values.
  • Permission errors: The integration lacks permission for the requested action. Update permissions in the connected application.
  • Rate limiting: Too many API calls in a short period. Wait and retry.
  • Timeout errors: The target application took too long to respond. Retry or check application status.
4

Check the inputs

Verify the inputs passed to the failed step were valid. Look for incorrect formats, missing required fields, or references to resources that no longer exist.
5

Fix and retry

Either re-run with corrected inputs, or fix the workflow logic and publish a new version.

​
Debug with the Workflow Builder Agent

The workflow builder agent can inspect recent runs and help you identify issues without manually digging through logs. Ask the builder agent to look at recent failures and it searches the 10 most recent runs of the workflow, identifies which runs failed, and pulls detailed task-level information including inputs, outputs, and status for each step.

​
How to use it

1

Open the workflow builder

Navigate to the workflow and open the builder chat.
2

Ask about failures

Describe what you want to investigate. For example:
  • “Why did this workflow fail?”
  • “What went wrong in the last run?”
  • “Show me the output of the failed step”
3

Review the agent's findings

The agent surfaces the exact error, the step that failed, and the input/output data for that step. It can also suggest fixes based on the error.
You do not need to copy run IDs or navigate to the Runs tab first. The agent searches recent runs automatically based on your question.

​
Tips for Faster Debugging

  • Check connected applications first. Many failures trace back to expired credentials or changed permissions in external systems.
  • Compare successful and failed runs. If the same workflow sometimes succeeds and sometimes fails, compare the inputs between a passing and failing run to isolate the difference.
  • Use the builder agent for pattern detection. Ask the agent to look across multiple recent failures to spot recurring issues.