Troubleshooting

Common issues and how to resolve them.

Run Failures

Max Steps Exceeded

Symptom: Run fails with “max_steps_exceeded”

Cause: Agent couldn’t complete within step limit

Solutions:

1. Increase max_steps in agent constraints
2. Simplify the task
3. Break into multiple agents/workflows
4. Check for infinite loops in logic

Timeout

Symptom: Run fails with “timeout”

Cause: Run exceeded max_duration

Solutions:

1. Increase max_duration
2. Optimize slow tools
3. Check for external system delays
4. Review step complexity

Token Limit

Symptom: Run fails with “token_limit_exceeded”

Cause: LLM token usage exceeded limit

Solutions:

1. Increase token limit
2. Reduce context size
3. Simplify system prompt
4. Use smaller model for simple tasks

Tool Failures

Tool Timeout

Symptom: Tool call fails with timeout

Cause: External system too slow

Solutions:

1. Increase tool_timeout
2. Check external system health
3. Implement retry logic
4. Use async processing

Authentication Errors

Symptom: Tool fails with 401/403

Cause: Invalid or expired credentials

Solutions:

1. Refresh integration credentials
2. Check permission scopes
3. Verify API key validity
4. Review access policies

Rate Limiting

Symptom: Tool fails with 429

Cause: Too many requests to external system

Solutions:

1. Implement backoff/retry
2. Reduce request frequency
3. Batch operations
4. Request rate limit increase

HITL Issues

Approval Timeout

Symptom: Run cancelled due to approval timeout

Cause: No response within timeout period

Solutions:

1. Increase decision_timeout
2. Set up escalation chain
3. Configure backup approvers
4. Review notification delivery

Wrong Approver

Symptom: Approvals going to wrong people

Cause: Notification configuration issue

Solutions:

1. Review notification settings
2. Check role assignments
3. Verify channel configurations

Debugging Steps

1. Check Run Status

query GetRun($id: ID!) {
  run(id: $id) {
    status
    failureReason
    steps {
      status
      error
    }
  }
}

2. Review Traces

Look at trace timeline for:

• Where execution stopped
• What the agent was thinking
• What tools were called
• Error details

3. Verify Configuration

Check agent settings:

• Constraints appropriate?
• Tools available?
• Model configured correctly?

4. Test Tools Individually

Verify tools work outside agent:

• Check credentials
• Test with sample inputs
• Verify permissions

Common Error Messages

Getting Help

If issues persist:

1. Export run details and traces
2. Check status page 
3. Search documentation
4. Contact support with run ID