Common Issues

This comprehensive troubleshooting guide helps you quickly resolve common issues in AgenticFlow. From agent configuration problems to workflow execution errors, find solutions to get your AI automation back on track.

🎯 Quick Issue Categories

Jump to your specific issue type:

• 🤖 Agent Issues - Agent creation, configuration, and performance problems

• ⚙️ Workflow Issues - Workflow execution, node errors, and bulk processing

• 🔗 Integration Issues - MCP connectors, OAuth, and API connections

• 📊 Knowledge Base Issues - File uploads, search problems, and RAG performance

• 💳 Credits & Billing - Usage tracking, limits, and payment issues

• 🔐 Authentication & Access - Login problems and permission errors

• ⚡ Performance Issues - Slow responses, timeouts, and optimization

---

🤖 Agent Issues

Agent Won't Respond or Gives Generic Answers

Symptoms:

• Agent provides vague, unhelpful responses

• Responses don't use knowledge base information

• Agent doesn't follow system prompt instructions

Common Causes & Solutions:

1. Ineffective System Prompt

// ❌ Vague prompt
{
  "system_prompt": "You are a helpful assistant."
}

// ✅ Specific, detailed prompt
{
  "system_prompt": "You are a customer support specialist for TechCorp's cloud platform. Always:\n1. Use knowledge base information to provide accurate answers\n2. Ask clarifying questions when requests are unclear\n3. Escalate complex technical issues to human support\n4. Maintain a professional, friendly tone\n5. Reference specific documentation when applicable"
}

2. Knowledge Base Not Connected

• Check: Verify knowledge base IDs are correctly added to agent

• Solution: Go to agent settings → Knowledge tab → Add relevant knowledge bases

• Verify: Test with a question that should use knowledge base content

3. Model Selection Issues

// Different models have different capabilities
{
  "model_recommendations": {
    "complex_reasoning": "claude-3-5-sonnet-20241022",
    "fast_responses": "gpt-4o-mini", 
    "creative_tasks": "gpt-4",
    "multilingual": "gemini-pro"
  }
}

4. Temperature Too High

// ❌ Too creative/random
{ "temperature": 0.9 }

// ✅ More focused for support
{ "temperature": 0.3 }

// ✅ Balanced for general use
{ "temperature": 0.7 }

"Agent Quota Exceeded" Error

Error Message: Agent limit reached for workspace

Solutions:

1. Check Current Usage:

   • Go to Dashboard → Usage → Agent Limits

   • Review active agent count vs. plan limits

2. Clean Up Unused Agents:

   • Deactivate agents not in use

   • Delete test/development agents

   • Archive old agents instead of keeping them active

3. Upgrade Plan:

   • Compare plans at Settings → Billing → Plans

   • Enterprise plans have unlimited agents

Agent Responses Are Too Slow

Symptoms:

• Response times >30 seconds

• Timeouts during conversations

• Poor user experience

Optimization Steps:

1. Model Optimization

{
  "performance_comparison": {
    "gpt-4o-mini": "~1-2s response time",
    "claude-3-5-sonnet": "~3-5s response time", 
    "gpt-4": "~5-10s response time",
    "claude-3-opus": "~10-15s response time"
  }
}

2. Knowledge Base Optimization

• Limit to 10 most relevant files

• Use focused, well-structured documents

• Remove duplicate or redundant content

3. Prompt Optimization

// ❌ Long, complex prompt
{
  "system_prompt": "Very long prompt with multiple instructions, examples, and complex formatting requirements that slows down processing..."
}

// ✅ Concise, clear prompt
{
  "system_prompt": "You are a support agent. Use knowledge base to answer questions accurately and concisely."
}

4. Token Limit Adjustment

// ❌ Unnecessarily high
{ "max_tokens": 4000 }

// ✅ Right-sized for use case
{ "max_tokens": 1000 } // For short responses

Agent Not Using Tools/Integrations

Symptoms:

• Agent doesn't call available tools

• Manual processes instead of automated actions

• Missing integration capabilities

Troubleshooting Steps:

1. Verify Tool Configuration

// Check agent tools configuration
GET /api/v1/agents/{agent_id}

// Response should include:
{
  "tool_ids": ["tool_slack_notify", "tool_crm_lookup"],
  "tools": [
    {
      "id": "tool_slack_notify",
      "name": "Slack Notification",
      "status": "active",
      "configuration": {...}
    }
  ]
}

2. Update System Prompt for Tool Usage

{
  "system_prompt": "You are a support agent with access to:\n- Slack notifications (use when escalating issues)\n- CRM lookup (use to find customer information)\n- Knowledge search (use to find documentation)\n\nAlways use appropriate tools to provide complete assistance."
}

3. Test Tools Individually

• Go to agent settings → Tools tab

• Test each tool independently

• Check for authentication/permission issues

---

⚙️ Workflow Issues

Workflow Execution Fails at Specific Node

Symptoms:

• Workflow stops at particular step

• "Node execution failed" error

• Inconsistent success rates

Diagnostic Steps:

1. Check Node Configuration

// Common LLM node issues
{
  "node_type": "llm",
  "common_issues": {
    "invalid_model": "Check model name spelling and availability",
    "prompt_too_long": "Reduce prompt length or use variables",
    "invalid_json_schema": "Validate JSON response format requirements",
    "missing_variables": "Ensure all {{variable}} references exist in input"
  }
}

2. Review Node Logs

• Go to Workflow → Executions → Select failed run

• Click on failed node to see detailed error message

• Check input/output data for issues

3. Common Node-Specific Issues

Email Node Issues:

{
  "common_email_errors": {
    "invalid_recipient": "Check email format and domain",
    "template_not_found": "Verify template ID exists",
    "authentication_failed": "Check SMTP or email service credentials",
    "rate_limit_exceeded": "Reduce sending frequency"
  }
}

API Node Issues:

{
  "common_api_errors": {
    "connection_timeout": "Increase timeout or check endpoint",
    "authentication_failed": "Verify API keys and headers", 
    "rate_limit": "Implement delays or request batching",
    "invalid_response": "Check API response format expectations"
  }
}

Bulk Workflow Processing Stalls

Symptoms:

• Large CSV/Excel processing stops midway

• "Processing" status for extended periods

• Incomplete results

Solutions:

1. Optimize Batch Size

{
  "batch_size_recommendations": {
    "simple_processing": 100,
    "llm_heavy": 25,
    "api_integrations": 50,
    "complex_workflows": 10
  }
}

2. Handle Rate Limits

{
  "rate_limit_strategy": {
    "add_delays": "Insert wait nodes between API calls",
    "reduce_parallel": "Lower concurrent batch processing",
    "implement_backoff": "Use exponential backoff for retries"
  }
}

3. Memory and Performance

• Break large files into smaller chunks

• Use streaming processing for large datasets

• Implement error handling and resume capability

Variable Substitution Not Working

Symptoms:

• {{variable_name}} appears in output instead of actual value

• "Variable not found" errors

• Unexpected empty values

Common Variable Issues:

1. Incorrect Variable Syntax

// ❌ Wrong formats
"{{variable name}}"  // Spaces not allowed
"{ variable }"       // Missing braces
"{{Variable}}"       // Case sensitive

// ✅ Correct format
"{{variable_name}}"

2. Variable Scope Problems

{
  "variable_scope": {
    "input_variables": "Available in all nodes",
    "node_outputs": "Use {{node_name.output_field}}",
    "global_variables": "Set in workflow settings",
    "local_variables": "Only in current node context"
  }
}

3. Data Type Mismatches

// ❌ Accessing array incorrectly
"{{user_data}}"  // Returns [object Object]

// ✅ Correct array access
"{{user_data.name}}"  // Specific field
"{{user_data[0]}}"    // First array item

---

🔗 Integration Issues

MCP Connector Authentication Failures

Symptoms:

• "Authentication failed" for MCP tools

• "Invalid credentials" errors

• Tools work manually but fail in workflows

Authentication Troubleshooting:

1. OAuth Issues

// Check OAuth token status
GET /api/v1/integrations/oauth-status

// Common OAuth problems:
{
  "expired_token": "Re-authenticate in settings",
  "invalid_scope": "Check required permissions",
  "revoked_access": "User revoked app access"
}

2. API Key Issues

{
  "api_key_checklist": {
    "correct_format": "Check for spaces or special characters",
    "proper_permissions": "Verify key has required scopes",
    "not_expired": "Check expiration date in service",
    "correct_environment": "Production vs. sandbox keys"
  }
}

3. Service-Specific Issues

Google Workspace:

• Enable required APIs in Google Cloud Console

• Check service account permissions

• Verify domain-wide delegation settings

Slack:

• Confirm bot has required channel permissions

• Check workspace installation status

• Verify bot token vs. user token usage

Microsoft 365:

• Check tenant admin consent

• Verify application permissions

• Confirm user has necessary licenses

Webhook Delivery Failures

Symptoms:

• Webhooks not reaching destination

• High failure rates in webhook logs

• Delayed or missing notifications

Webhook Debugging:

1. Check Endpoint Availability

# Test webhook endpoint manually
curl -X POST https://your-app.com/webhook \
  -H "Content-Type: application/json" \
  -d '{"test": "data"}'

2. Review Webhook Configuration

{
  "webhook_requirements": {
    "https_only": "HTTP endpoints are not supported",
    "response_codes": "Return 2xx status codes",
    "timeout": "Respond within 10 seconds",
    "content_type": "Accept application/json"
  }
}

3. Authentication Issues

{
  "webhook_auth": {
    "signature_verification": "Verify HMAC signature if configured",
    "api_key_headers": "Check X-API-Key or custom headers",
    "ip_allowlist": "Ensure webhook IPs are allowed"
  }
}

---

📊 Knowledge Base Issues

Files Won't Upload or Process

Symptoms:

• Upload stuck at 0% or 99%

• "Processing failed" errors

• Files appear uploaded but content not searchable

File Upload Solutions:

1. Check File Specifications

{
  "supported_formats": ["pdf", "docx", "txt", "md", "csv"],
  "max_file_size": "100MB",
  "max_files_per_agent": 10,
  "total_storage_limit": "1GB per agent"
}

2. File Quality Issues

{
  "file_quality_checklist": {
    "readable_text": "Scanned PDFs need OCR processing",
    "proper_encoding": "Use UTF-8 for text files",
    "not_corrupted": "Verify file opens normally",
    "reasonable_size": "Very large files may timeout"
  }
}

3. Processing Optimization

• Break large documents into smaller sections

• Use clear, well-structured content

• Remove unnecessary formatting and images

• Ensure documents are text-searchable

Knowledge Base Search Not Working

Symptoms:

• Agent doesn't find relevant information

• Search returns no results

• Incorrect or irrelevant content retrieved

Search Optimization:

1. Content Structure

# ✅ Well-structured content
## Customer Refund Policy

**Eligibility**: Customers can request refunds within 30 days...
**Process**: To request a refund, customers should...
**Timeline**: Refunds are processed within 5-7 business days...

# ❌ Poor structure  
Customer refund policy customers can request refunds sometimes we allow them but it depends on various factors...

2. Search Configuration

{
  "search_optimization": {
    "similarity_threshold": 0.7,  // Adjust for relevance
    "max_results": 5,            // Limit to most relevant
    "include_metadata": true,    // Add context
    "chunk_overlap": 100         // Ensure context continuity
  }
}

3. Content Guidelines

• Use specific, descriptive headings

• Include relevant keywords naturally

• Avoid duplication across documents

• Add context and examples

• Keep information current and accurate

10-File Limit Optimization

Symptoms:

• Need more knowledge but hit 10-file limit

• Difficulty choosing which files to include

• Performance issues with large knowledge base

Optimization Strategies:

1. File Consolidation

{
  "consolidation_approach": {
    "merge_related": "Combine similar topics into single files",
    "create_summaries": "Use summary documents for comprehensive topics",
    "prioritize_frequently_used": "Keep most-accessed content",
    "remove_outdated": "Delete obsolete information"
  }
}

2. Strategic File Selection

{
  "file_priority_matrix": {
    "high_priority": "Core business processes, FAQ, policies",
    "medium_priority": "Product documentation, procedures", 
    "low_priority": "Background information, historical data"
  }
}

3. Content Quality over Quantity

• Focus on comprehensive, well-written documents

• Ensure each file serves a distinct purpose

• Regular review and update cycle

• Use external links for supplementary information

---

💳 Credits & Billing

Unexpected High Credit Usage

Symptoms:

• Credits depleting faster than expected

• Usage spikes without obvious cause

• Budget alerts triggering frequently

Usage Analysis:

1. Check Usage Dashboard

• Go to Dashboard → Usage → Credit Breakdown

• Identify highest-consuming agents/workflows

• Review usage patterns and trends

2. Common High-Usage Causes

{
  "high_usage_patterns": {
    "long_conversations": "Agents with extended back-and-forth",
    "large_knowledge_bases": "Processing many documents",
    "complex_workflows": "Multi-step processes with multiple LLM calls",
    "bulk_processing": "Large dataset processing",
    "inefficient_prompts": "Verbose prompts and responses"
  }
}

3. Optimization Strategies

{
  "cost_optimization": {
    "model_selection": "Use faster, cheaper models for simple tasks",
    "prompt_efficiency": "Reduce prompt length and complexity",
    "caching": "Avoid repeated similar processing",
    "batch_processing": "Group similar operations",
    "response_limits": "Set appropriate max_tokens limits"
  }
}

"Quota Exceeded" Errors

Error Messages:

• Monthly credit limit exceeded

• Rate limit reached

• Workspace quota exceeded

Solutions:

1. Check Current Limits

// API call to check quotas
GET /api/v1/account/quotas

{
  "monthly_credits": {
    "used": 8500,
    "limit": 10000,
    "remaining": 1500
  },
  "rate_limits": {
    "api_calls_per_minute": 100,
    "workflow_executions_per_minute": 25
  }
}

2. Immediate Actions

• Pause non-critical workflows

• Reduce batch processing sizes

• Switch to more efficient models temporarily

• Add credits or upgrade plan

3. Long-term Solutions

• Implement usage monitoring and alerts

• Optimize workflows for efficiency

• Set up auto-scaling credit policies

• Consider enterprise plans for higher limits

---

🔐 Authentication & Access

Can't Log In or Access Workspace

Symptoms:

• Login page shows errors

• "Access denied" messages

• Can't see expected workspaces/resources

Authentication Troubleshooting:

1. Basic Login Issues

{
  "login_checklist": {
    "correct_email": "Check for typos in email address",
    "password_accuracy": "Verify password case sensitivity",
    "account_exists": "Confirm account was properly created",
    "email_verified": "Check for verification email"
  }
}

2. SSO and Enterprise Login

• Check with IT administrator for SSO status

• Verify corporate email domain configuration

• Ensure user is provisioned in identity provider

• Check for active directory synchronization

3. Workspace Access Issues

{
  "workspace_access": {
    "not_invited": "Contact workspace administrator for invitation",
    "role_permissions": "Verify assigned role has required permissions",
    "account_status": "Check if account is active/suspended",
    "workspace_status": "Confirm workspace is not archived"
  }
}

API Authentication Failures

Symptoms:

• 401 Unauthorized errors in API calls

• "Invalid API key" messages

• Intermittent authentication issues

API Auth Solutions:

1. API Key Verification

# Test API key
curl -H "Authorization: Bearer af_live_your_key_here" \
     https://api.agenticflow.ai/v1/account

# Check response for validity

2. Common API Key Issues

{
  "api_key_problems": {
    "wrong_environment": "Test keys (af_test_) vs Live keys (af_live_)",
    "expired_key": "Keys can expire - check key management",
    "revoked_access": "Key may have been revoked in settings",
    "incorrect_format": "Ensure Bearer token format is correct"
  }
}

3. Permissions and Scopes

{
  "permission_errors": {
    "insufficient_scope": "API key lacks required permissions",
    "workspace_restrictions": "Key limited to specific workspaces",
    "role_limitations": "User role doesn't allow API access",
    "resource_restrictions": "Can't access specific resources"
  }
}

---

⚡ Performance Issues

Slow Platform Response Times

Symptoms:

• Pages load slowly (>5 seconds)

• Timeout errors during operations

• Laggy user interface interactions

Performance Troubleshooting:

1. Browser and Network

{
  "browser_optimization": {
    "clear_cache": "Clear browser cache and cookies",
    "disable_extensions": "Test with browser extensions disabled",
    "try_incognito": "Use private/incognito mode",
    "update_browser": "Ensure browser is up to date"
  }
}

2. Network Connectivity

# Test connection speed
ping api.agenticflow.ai

# Check for proxy/firewall issues
curl -I https://app.agenticflow.ai

3. Platform Status

• Check Status Page

• Look for ongoing maintenance or incidents

• Review performance metrics and alerts

Workflow Execution Timeouts

Symptoms:

• Workflows fail with timeout errors

• Long-running processes never complete

• Inconsistent execution times

Timeout Solutions:

1. Optimize Workflow Design

{
  "timeout_optimization": {
    "break_into_smaller_steps": "Split complex operations",
    "parallel_processing": "Run independent steps simultaneously",
    "reduce_data_size": "Process smaller batches",
    "optimize_prompts": "Use more efficient prompts"
  }
}

2. Adjust Timeout Settings

{
  "timeout_configuration": {
    "workflow_timeout": 1800,  // 30 minutes max
    "node_timeout": 300,       // 5 minutes per node
    "api_timeout": 60,         // 1 minute for API calls
    "llm_timeout": 120         // 2 minutes for AI responses
  }
}

3. Error Handling

{
  "retry_strategy": {
    "max_retries": 3,
    "retry_delay": "exponential",
    "retry_conditions": ["timeout", "temporary_failure"],
    "fallback_actions": ["notify_admin", "save_partial_results"]
  }
}

---

🆘 Getting Additional Help

When to Contact Support

Contact support for:

• Platform bugs or unexpected errors

• Data loss or corruption issues

• Security concerns

• Enterprise feature questions

• Custom integration requirements

How to Get Effective Support

1. Gather Information Before Contacting

{
  "support_information": {
    "error_messages": "Copy exact error text",
    "steps_to_reproduce": "List what you did before the issue",
    "browser_info": "Browser type, version, and OS",
    "account_details": "Workspace ID, user role, plan type",
    "screenshots": "Visual evidence of the issue"
  }
}

2. Support Channels

• Discord Community: qra.ai/discord

• Email Support: [email protected]

• Enterprise Support: [email protected]

• Developer Support: [email protected]

3. Response Time Expectations

{
  "response_times": {
    "community_discord": "Usually < 2 hours during business hours",
    "email_support": "24-48 hours for most issues",
    "enterprise_support": "4-8 hours with dedicated support",
    "critical_issues": "1-2 hours for platform outages"
  }
}

Self-Service Resources

Before contacting support, try:

• Documentation - Comprehensive guides and tutorials

• API Reference - Complete API documentation

• Video Tutorials - Step-by-step video guides

• Community Discord - User community and discussions

• Status Page - Current platform status

---

📊 Issue Resolution Checklist

Use this checklist to systematically troubleshoot issues:

Basic Diagnostics ✅

• Clear browser cache and cookies

• Try different browser or incognito mode

• Check platform status page

• Verify internet connection stability

• Confirm account has necessary permissions

Configuration Review ✅

• Double-check all settings and configurations

• Verify API keys and authentication

• Review recent changes that might affect functionality

• Check quotas and usage limits

• Validate input data format and content

Error Analysis ✅

• Copy and analyze exact error messages

• Check execution logs for detailed information

• Identify patterns in when issues occur

• Test with minimal/simplified configurations

• Reproduce issue with step-by-step documentation

Resolution Attempt ✅

• Apply relevant solutions from this guide

• Test changes incrementally

• Document what works and what doesn't

• Revert changes if issues worsen

• Contact support if issues persist

---

🔧 Most AgenticFlow issues can be resolved quickly with the right troubleshooting approach. This guide provides solutions for the most common problems, but don't hesitate to reach out to our support team if you need additional assistance.

Get back to building amazing AI automation - we're here to help!