# 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:** ```javascript // 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:** ```json { "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:** ```javascript // 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:** ```json { "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 ```bash # 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:** ```json { "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:** ```json // 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:** ```json { "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:** ```javascript // 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:** ```javascript // 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:** ```javascript // 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:** ```json { "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:** ```bash # 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 ```bash # 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:** ```bash # 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:** ```javascript // 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 ```bash # 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:** ```bash # 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:** * Email: * Include request ID: `123456789` * Describe steps to reproduce ### **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: ```bash # 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** ```bash # 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: ```bash # 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: ```javascript // 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: ```javascript 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](https://status.agenticflow.ai) 3. **Documentation**: This error reference 4. **Community**: [Discord](https://qra.ai/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** * **Discord**: - Community support * **Email**: - Direct support * **Status Updates**: [status.agenticflow.ai](https://status.agenticflow.ai) - System status *** **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 so we can add it to this reference.