HomeCommunityDiscordLogin

Error Reference

Complete reference for troubleshooting AgenticFlow errors, with causes and solutions.

This comprehensive error reference helps you quickly identify and resolve issues in AgenticFlow agents, workflows, and integrations. Each error includes the root cause, immediate solutions, and prevention strategies.

🚨 Error Categories

Agent Errors

Issues related to AI agents, conversations, and configurations.

Workflow Errors

Problems with workflow execution, nodes, and data processing.

Integration Errors

External service connections, APIs, and authentication issues.

System Errors

Platform-level issues, rate limits, and resource constraints.

Authentication Errors

API keys, permissions, and access control problems.

🤖 Agent Errors

AGENT_NOT_FOUND

Error Message: Agent with ID 'agent_123' not found

Cause:

  • Agent was deleted

  • Incorrect agent ID

  • Agent belongs to different workspace

Solution:

// Verify agent exists
GET /api/v1/agents/agent_123

// List all agents in workspace
GET /api/v1/agents

Prevention:

  • Store agent IDs consistently

  • Check agent existence before API calls

  • Use agent name lookup when possible

AGENT_CONFIGURATION_ERROR

Error Message: Agent configuration is invalid: Missing system prompt

Common Issues:

  • Empty or missing system prompt

  • Invalid model selection

  • Malformed JSON in configuration

  • Missing required fields

Solution:

{
  "system_prompt": "You are a helpful assistant...",
  "model": "gpt-4",
  "temperature": 0.7,
  "max_tokens": 1000
}

Prevention:

  • Validate configuration before saving

  • Use configuration templates

  • Test agent after changes

CONVERSATION_LIMIT_EXCEEDED

Error Message: Maximum concurrent conversations exceeded (limit: 50)

Cause:

  • Too many active conversations

  • Conversations not properly closed

  • High traffic exceeding plan limits

Solution:

// Close inactive conversations
POST /api/v1/conversations/{conversation_id}/close

// Check conversation limits
GET /api/v1/workspace/limits

Prevention:

  • Implement conversation cleanup

  • Monitor active conversation counts

  • Upgrade plan for higher limits

MODEL_UNAVAILABLE

Error Message: Model 'gpt-4-turbo' is temporarily unavailable

Cause:

  • Model provider downtime

  • Rate limiting from provider

  • Model deprecated or removed

Solution:

{
  "model": "gpt-4",
  "fallback_model": "gpt-3.5-turbo"
}

Prevention:

  • Configure fallback models

  • Monitor model status

  • Use multiple model providers

⚡ Workflow Errors

WORKFLOW_EXECUTION_FAILED

Error Message: Workflow execution failed at step 3: API call timeout

Common Causes:

  • Node configuration errors

  • Network timeouts

  • Invalid input data

  • Missing required parameters

Debugging Steps:

  1. Check execution logs

  2. Verify node configurations

  3. Test individual nodes

  4. Validate input data

# Get detailed execution logs
GET /api/v1/workflows/{workflow_id}/executions/{execution_id}/logs

NODE_CONFIGURATION_ERROR

Error Message: Node 'send_email' missing required parameter: recipient

Solution:

{
  "node_id": "send_email",
  "configuration": {
    "recipient": "{{customer_email}}",
    "subject": "Thank you for your order",
    "body": "Your order has been processed..."
  }
}

Common Missing Parameters:

  • API Call: URL, method, headers

  • Email: recipient, subject, body

  • Database: connection string, query

  • File Operations: file path, format

VARIABLE_SUBSTITUTION_ERROR

Error Message: Variable '{{customer_name}}' not found in context

Cause:

  • Variable name typo

  • Variable not set in previous step

  • Incorrect variable scope

Solution:

// Check available variables
{
  "available_variables": [
    "customer_email",
    "order_id",
    "total_amount"
  ],
  "missing_variables": [
    "customer_name"
  ]
}

Prevention:

  • Use variable autocomplete

  • Test with sample data

  • Validate variable paths

INFINITE_LOOP_DETECTED

Error Message: Workflow stopped: Infinite loop detected in step 'check_status'

Cause:

  • Loop condition never becomes false

  • Missing exit condition

  • Recursive workflow calls

Solution:

{
  "loop_configuration": {
    "max_iterations": 100,
    "exit_condition": "{{status}} === 'completed'",
    "timeout_seconds": 300
  }
}

DATA_TRANSFORMATION_ERROR

Error Message: Failed to parse JSON: Unexpected token at position 45

Common Issues:

  • Malformed JSON input

  • Incorrect data type conversion

  • Missing required fields

  • Character encoding issues

Solution:

// Validate JSON before processing
try {
  const parsed = JSON.parse(inputData);
  return parsed;
} catch (error) {
  throw new Error(`Invalid JSON: ${error.message}`);
}

🔗 Integration Errors

API_AUTHENTICATION_FAILED

Error Message: Authentication failed for service 'slack': Invalid token

Causes:

  • Expired OAuth tokens

  • Invalid API keys

  • Revoked permissions

  • Wrong authentication method

Solution:

// Refresh OAuth token
POST /api/v1/connections/slack/refresh

// Update API key
PUT /api/v1/connections/service_name
{
  "api_key": "new_api_key_here"
}

Prevention:

  • Monitor token expiration

  • Implement automatic refresh

  • Use secure key storage

API_RATE_LIMIT_EXCEEDED

Error Message: Rate limit exceeded for OpenAI API: 60 requests per minute

Solution:

// Implement exponential backoff
const delay = Math.pow(2, retryCount) * 1000;
await new Promise(resolve => setTimeout(resolve, delay));

Prevention:

  • Batch API requests

  • Implement rate limiting

  • Use multiple API keys

  • Monitor usage patterns

CONNECTION_TIMEOUT

Error Message: Connection timeout to external service after 30 seconds

Causes:

  • Network connectivity issues

  • Slow external service

  • Firewall blocking requests

  • Service overload

Solution:

{
  "timeout_settings": {
    "connect_timeout": 10,
    "read_timeout": 30,
    "retry_attempts": 3
  }
}

WEBHOOK_DELIVERY_FAILED

Error Message: Webhook delivery failed: HTTP 500 Internal Server Error

Common Issues:

  • Target endpoint down

  • Invalid webhook URL

  • Payload too large

  • Authentication errors

Debugging:

# Check webhook logs
GET /api/v1/webhooks/{webhook_id}/logs

# Test webhook endpoint
POST /api/v1/webhooks/{webhook_id}/test

🔐 Authentication Errors

INVALID_API_KEY

Error Message: Invalid API key provided

Solution:

  1. Verify API key format

  2. Check key hasn't been revoked

  3. Ensure correct workspace

  4. Regenerate if necessary

# Get API key info
GET /api/v1/auth/key-info
Authorization: Bearer your_api_key

PERMISSION_DENIED

Error Message: Insufficient permissions to access resource 'workflows'

Causes:

  • User role restrictions

  • Workspace-level permissions

  • Resource-specific access controls

Solution:

# Check user permissions
GET /api/v1/users/me/permissions

# Update user role
PUT /api/v1/users/{user_id}/role
{
  "role": "admin"
}

TOKEN_EXPIRED

Error Message: Access token has expired

Solution:

// Refresh access token
POST /api/v1/auth/refresh
{
  "refresh_token": "your_refresh_token"
}

💳 Billing & Credit Errors

INSUFFICIENT_CREDITS

Error Message: Insufficient credits: Required 5.0, available 2.5

Immediate Solutions:

  1. Purchase more credits

  2. Upgrade subscription plan

  3. Optimize usage to reduce costs

# Check credit balance
GET /api/v1/billing/credits

# Purchase credits
POST /api/v1/billing/credits/purchase
{
  "amount": 1000,
  "payment_method": "card_123"
}

PAYMENT_FAILED

Error Message: Payment processing failed: Card declined

Solutions:

  1. Update payment method

  2. Contact bank about declined transaction

  3. Try alternative payment method

USAGE_LIMIT_EXCEEDED

Error Message: Monthly usage limit exceeded: 10,000 credits

Solutions:

  1. Upgrade to higher plan

  2. Wait for next billing cycle

  3. Purchase additional credit buckets

🖥️ System Errors

SERVICE_UNAVAILABLE

Error Message: Service temporarily unavailable: High load detected

User Actions:

  1. Wait and retry request

  2. Implement exponential backoff

  3. Check status page for updates

Status Monitoring:

# Check system status
GET https://status.agenticflow.ai/api/v1/status

INTERNAL_SERVER_ERROR

Error Message: Internal server error: Request ID 123456789

User Actions:

  1. Retry the request

  2. Contact support with request ID

  3. Check for system-wide issues

Support Information:

DATABASE_CONNECTION_ERROR

Error Message: Database temporarily unavailable

System Response:

  • Automatic retry with backoff

  • Failover to backup systems

  • User notification if extended

🛠️ Debugging Tools

Execution Logs

Access detailed execution information:

# Get workflow execution logs
GET /api/v1/workflows/{workflow_id}/executions/{execution_id}/logs

# Get agent conversation logs
GET /api/v1/agents/{agent_id}/conversations/{conversation_id}/logs

System Health Check

# Check overall system health
GET /api/v1/health

# Response
{
  "status": "healthy",
  "services": {
    "database": "healthy",
    "ai_services": "healthy",
    "external_apis": "degraded"
  },
  "response_time_ms": 45
}

Usage Analytics

Monitor your usage patterns to prevent errors:

# Get usage statistics
GET /api/v1/analytics/usage?period=24h

# Response
{
  "total_requests": 1250,
  "error_rate": 0.02,
  "avg_response_time": 850,
  "top_errors": [
    {"type": "RATE_LIMIT_EXCEEDED", "count": 15},
    {"type": "TIMEOUT", "count": 8}
  ]
}

🚀 Error Prevention Strategies

Proactive Monitoring

Set up alerts for common issues:

// Example monitoring setup
const monitoring = {
  error_rate_threshold: 0.05, // 5%
  response_time_threshold: 2000, // 2 seconds
  credit_balance_threshold: 100, // Low credits
  failed_webhook_threshold: 10 // Failed deliveries
};

Graceful Error Handling

Implement robust error handling in your applications:

async function callAgenticFlowAPI(endpoint, data) {
  try {
    const response = await fetch(`https://api.agenticflow.ai${endpoint}`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(data)
    });
    
    if (!response.ok) {
      const error = await response.json();
      throw new Error(`API Error: ${error.message}`);
    }
    
    return await response.json();
  } catch (error) {
    console.error('AgenticFlow API Error:', error);
    
    // Implement retry logic for transient errors
    if (error.status >= 500) {
      return await retryWithBackoff(() => 
        callAgenticFlowAPI(endpoint, data)
      );
    }
    
    throw error;
  }
}

Testing & Validation

Prevent errors through comprehensive testing:

  • Unit Tests: Test individual components

  • Integration Tests: Test external connections

  • Load Tests: Verify performance under stress

  • Error Simulation: Test error handling paths

📞 Getting Help

Self-Service Resources

  1. Error Logs: Check execution logs first

  2. Status Page: status.agenticflow.ai

  3. Documentation: This error reference

  4. Community: Discord

Support Escalation

When contacting support, include:

  • Error Message: Exact error text

  • Request ID: From error response

  • Steps to Reproduce: What you were doing

  • Expected vs Actual: What should have happened

  • Environment: Browser, API client, etc.

Support Channels

Most errors in AgenticFlow are quickly resolvable with the right information. This reference guide provides the knowledge you need to diagnose and fix issues efficiently. When in doubt, our support team and community are here to help.

Found an error not covered here? Let us know at [email protected] so we can add it to this reference.

PreviousCommon IssuesNextPerformance Issues

Last updated

Was this helpful?