Fix n8n AI Agent Errors: Complete Troubleshooting Guide

Your AI agent just stopped working in the middle of a production workflow. No warning. No clear error message. Just a cryptic failure that worked perfectly five minutes ago.

This moment hits every n8n builder eventually. You’ve configured the agent correctly. The tools work individually. Memory is connected. But something breaks anyway.

The Frustrating Reality

AI agents fail differently than regular n8n nodes.

A broken HTTP Request gives you a status code. A failed Code node shows the exact line that crashed. But an AI agent? The failure modes are maddening:

• Silently returns nothing while appearing to succeed
• Hallucinates tool results it never actually retrieved
• Loops infinitely burning through your API credits
• Picks the wrong tool for obvious requests
• Works in testing, fails in production with no explanation

The n8n community forums overflow with these questions. Developers spend hours tweaking prompts and swapping models before finding the issue buried in a detail they never suspected.

The root cause is almost always the same: AI agents operate in loops, and loop failures cascade in unexpected ways.

Why Standard Debugging Fails

A single user request might trigger a dozen internal operations:

1. Agent receives input
2. Agent decides which tool to call
3. Tool executes and returns data
4. Agent interprets the result
5. Agent decides if more actions are needed
6. Repeat until complete

When something goes wrong at step 4, the agent compensates at step 5, making things worse. By the time you see the output, the root cause is buried.

You can’t just check input and output. You need to understand the entire reasoning chain.

What You’ll Learn

• A systematic debugging framework for diagnosing any AI agent error
• How to fix tool selection problems when agents ignore or misuse tools
• Stopping infinite loops and runaway token costs
• Resolving output parsing failures that break downstream workflows
• Debugging memory and context issues across conversations
• Handling rate limiting and API errors gracefully
• Detecting and preventing agent hallucination
• Production debugging patterns with logging and circuit breakers
• Model-specific troubleshooting for OpenAI, Anthropic, and local models
• Prevention patterns that stop errors before they happen

The AI Agent Debugging Framework

Before diving into specific errors, you need a systematic approach. Random changes to prompts and settings waste time and often make things worse.

The Three-Stage Methodology

Stage 1: Identify the Symptom Category

AI agent failures fall into distinct patterns:

Symptom	Likely Category
Agent responds without calling tools	Tool Selection
Execution runs for minutes, token spike	Infinite Loop
”Could not parse LLM output” error	Output Parsing
Agent forgets previous messages	Memory/Context
429 errors, sudden failures	Rate Limiting
Confident but wrong responses	Hallucination
Works in testing, fails in production	Environment

Identify your symptom first. Don’t guess at causes.

Stage 2: Diagnose the Root Cause

Each symptom category has specific diagnostic steps. Check execution logs in n8n to see exactly what the agent “thought” at each step:

1. Go to Executions in n8n
2. Click on the failed execution
3. Click the AI Agent node
4. Expand output to see reasoning steps, tool calls, and responses

The logs reveal what the agent decided and why. Most fixes become obvious once you see the actual decision chain.

Stage 3: Apply the Targeted Fix

Use the specific fix for your diagnosed root cause. Avoid broad changes like “rewrite the entire prompt” or “switch models” until you understand what went wrong.

When to Debug vs Rebuild

Debug when:

• The agent worked before and recently broke
• The failure is intermittent
• You can isolate the problem to specific inputs

Rebuild when:

• The agent never worked reliably
• You have more than 6-7 tools
• The system prompt exceeds 2,000 words
• You’re fighting the architecture constantly

Sometimes the fastest fix is a simpler design. Our AI Agent vs LLM Chain comparison helps determine if an agent is even the right choice for your use case.

Tool Selection Errors

The most common AI agent failure: the agent ignores your carefully configured tools or picks the wrong one for obvious requests.

Symptoms

• Agent responds with generic text instead of using tools
• Wrong tool called for the request type
• "Tool not found" or "No tool with name" errors
• Agent claims it doesn’t have access to capabilities you connected

Root Causes

Vague tool descriptions. The LLM decides which tool to use based solely on the description you provide. A description like “Use this for data” gives no guidance.

Overlapping tool purposes. If two tools have similar descriptions, the agent can’t reliably choose between them. “Search for products” and “Find product information” confuse the model.

Too many tools. Research shows agent reliability drops significantly beyond 5-7 tools. More tools mean more decisions, and LLMs make worse decisions when overwhelmed with options.

Description format issues. Some providers expect specific formats. Including examples in descriptions helps the model understand when to use each tool.

Fixes

Write specific, distinct tool descriptions:

Bad:
"Use this for customer data"

Good:
"Look up customer account information by email address.
Input: Customer email (e.g., [email protected])
Output: Customer profile including name, account status, and order history.
Use when: User asks about their account, order status, or purchase history."

Reduce tool count. If you have more than 6 tools, consolidate related capabilities or split into multiple specialized agents. Our multi-agent orchestration guide covers delegation patterns.

Test tool selection explicitly. Before production deployment, test with inputs that should trigger each tool:

// Test cases for validation
const testCases = [
  { input: "What's my order status for order 12345?", expectedTool: "order_lookup" },
  { input: "Do you have the iPhone 15 in stock?", expectedTool: "inventory_check" },
  { input: "I want a refund", expectedTool: "escalate_ticket" }
];

Add tool guidance to your system prompt:

AVAILABLE TOOLS AND WHEN TO USE THEM:
- order_lookup: For ANY question about order status, shipping, or delivery
- inventory_check: For product availability and stock questions
- escalate_ticket: For complaints, refunds, or issues requiring human review

IMPORTANT: Always use the appropriate tool before responding.
Do not answer questions about orders without first using order_lookup.

For comprehensive tool configuration guidance, see our AI Agent node documentation.

Infinite Loop and Iteration Errors

Your workflow runs for minutes. Token costs spike. Eventually, it times out or returns an incomplete response. The agent is stuck in a reasoning loop.

Symptoms

• Execution duration stretches to minutes for simple requests
• Token usage 5-10x higher than expected
• Timeout errors with no useful output
• Same tool called repeatedly with similar parameters
• "Max iterations exceeded" warnings

Root Causes

No completion criteria. The agent doesn’t know when it’s done. Without explicit instructions about what constitutes a complete answer, it keeps searching for more information.

Ambiguous tool results. If a tool returns null, an empty array, or an error message the agent doesn’t understand, it might retry indefinitely.

Goal too broad. “Research everything about this topic” invites infinite expansion. Every search reveals more to search.

Model confusion. Some LLMs struggle with knowing when to stop, especially with complex multi-step tasks.

Fixes

Add explicit completion criteria to your prompt:

COMPLETION RULES:
1. After successfully retrieving order information, summarize and respond
2. If a tool returns no results, inform the user and suggest alternatives
3. Never call the same tool more than 3 times for the same request
4. Once you have enough information to answer, stop searching and respond

Validate tool responses before passing to the agent:

// In a Code node before returning tool results
const toolResult = $json.toolOutput;

if (!toolResult || toolResult.length === 0) {
  return [{
    json: {
      result: "NO_DATA_FOUND",
      message: "No matching records found. Ask the user for different search criteria."
    }
  }];
}

if (toolResult.error) {
  return [{
    json: {
      result: "TOOL_ERROR",
      message: `Tool encountered an error: ${toolResult.error}. Do not retry.`
    }
  }];
}

return $input.all();

Set iteration limits. Some chat model configurations allow setting maximum iterations. If not available, wrap your agent in a timeout using workflow settings.

Detect loop patterns with a counter:

// Track tool calls in workflow static data
const staticData = $getWorkflowStaticData('global');
const callKey = `${$json.sessionId}_${$json.toolName}`;

staticData[callKey] = (staticData[callKey] || 0) + 1;

if (staticData[callKey] > 3) {
  // Force exit
  return [{
    json: {
      error: "LOOP_DETECTED",
      message: "Maximum tool calls exceeded. Provide best available answer."
    }
  }];
}

For timeout configuration strategies, see our timeout troubleshooting guide.

Output Parsing Failures

Your agent processes the request successfully, but downstream nodes crash because the output isn’t in the expected format. JSON is malformed. Required fields are missing. The schema validation fails.

Symptoms

• "Could not parse LLM output" errors
• "Unexpected token" JSON parsing errors
• Inconsistent output structure across executions
• Schema validation failures in downstream nodes
• Agent includes reasoning text mixed with JSON output

Root Causes

Agent reasoning interferes with structured output. Unlike a simple LLM call, agents have internal reasoning steps. These thinking processes sometimes leak into the final output, breaking expected formats.

Temperature too high. Higher temperature increases creativity but also variation. An agent with temperature 0.9 produces different output formats across runs.

Complex schemas. Deeply nested objects with many required fields increase failure probability. The more complex the schema, the more likely the agent misformats something.

Model limitations. Not all LLMs handle structured output equally well. Smaller or local models may struggle with complex JSON requirements.

Fixes

Use the hybrid pattern. Let the agent reason freely, then format with a dedicated chain. This separation dramatically improves reliability:

[Trigger] → [AI Agent] → [Edit Fields: extract response] → [Basic LLM Chain + Output Parser] → [Output]

The agent handles complex reasoning and tool use. A separate Basic LLM Chain with an output parser handles final formatting. Each component does what it’s best at.

Lower temperature for structured output.

// In chat model configuration
{
  "temperature": 0,  // Most deterministic
  "model": "gpt-4"   // Or your preferred model
}

Simplify the schema. Flatten nested structures. Remove optional fields that aren’t essential. Test with a minimal schema first, then add complexity:

{
  "type": "object",
  "properties": {
    "answer": { "type": "string" },
    "confidence": { "type": "number" },
    "sources": { "type": "array", "items": { "type": "string" } }
  },
  "required": ["answer"]
}

Add fallback parsing:

// In a Code node after the agent
let response = $json.output;

// Try to extract JSON from response
const jsonMatch = response.match(/\{[\s\S]*\}/);
if (jsonMatch) {
  try {
    return [{ json: JSON.parse(jsonMatch[0]) }];
  } catch (e) {
    // Parsing failed
  }
}

// Fallback: return raw response wrapped
return [{
  json: {
    rawResponse: response,
    parseError: true
  }
}];

Memory and Context Errors

The agent forgets what happened earlier in the conversation. Or worse, it loads the wrong conversation entirely. Multi-turn interactions break down.

Symptoms

• Agent asks for information already provided
• Context from earlier messages is missing
• Wrong conversation history appears
• "Context window exceeded" errors
• Memory-related database errors

Root Causes

Session ID misconfiguration. The session ID determines which conversation to load. A dynamic expression that changes between requests causes each message to start fresh.

Memory type mismatch. Simple Memory disappears when the workflow ends. Using it for production conversations means lost context on every restart.

Unbounded history growth. Without limits, conversation history grows until it exceeds the model’s context window or causes memory pressure.

Database connection issues. Postgres or Redis memory types fail silently if the database is unreachable, defaulting to no memory.

Fixes

Verify session ID consistency:

// Correct: stable session ID per conversation
const sessionId = `user_${$json.userId}_conv_${$json.conversationId}`;

// Wrong: includes timestamp that changes every message
const badSessionId = `session_${Date.now()}`;  // Creates new session each time

Choose the right memory type:

Use Case	Memory Type
Testing only	Simple Memory
Short interactions	Window Buffer Memory
Production conversations	Postgres Chat Memory
High-performance needs	Redis Chat Memory
Semantic recall	Vector Store Memory

Set window limits to prevent overflow:

// Window Buffer Memory configuration
{
  "contextWindowLength": 10  // Keep last 10 messages
}

Debug memory loading:

// Add a Code node before the agent to inspect loaded memory
const memory = $json.chatHistory || [];
console.log(`Session: ${$json.sessionId}, Messages loaded: ${memory.length}`);

if (memory.length === 0 && $json.isFollowUp) {
  // Expected history but got none
  console.error('Memory load failed or session ID mismatch');
}

return $input.all();

Test database connectivity:

// Quick Postgres connectivity check
const testQuery = await this.helpers.request({
  method: 'GET',
  uri: 'your-postgres-health-endpoint'
});

For database setup, see our Postgres setup guide.

Rate Limiting and API Errors

Your workflow suddenly fails with 429 errors. Or it worked for the first few executions but dies under load. API costs spike unexpectedly.

Symptoms

• 429 Too Many Requests errors
• "Rate limit exceeded" messages
• Workflows fail during high-traffic periods
• Token or cost quota exhausted
• Sporadic failures that succeed on retry

Root Causes

No rate limiting implementation. Without throttling, burst traffic overwhelms provider limits.

Retry storm patterns. Aggressive retries on failure amplify the problem. Ten failed requests become a hundred retries.

Parallel execution issues. Multiple workflow executions hitting the API simultaneously exceed per-minute limits.

Token budget exhaustion. Monthly or daily token limits hit mid-workflow.

Fixes

Implement exponential backoff:

// Retry logic with exponential backoff
async function callWithRetry(fn, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (error.statusCode === 429 && attempt < maxRetries - 1) {
        const delay = Math.pow(2, attempt) * 1000;  // 1s, 2s, 4s
        await new Promise(r => setTimeout(r, delay));
        continue;
      }
      throw error;
    }
  }
}

Add rate limiting in your workflow:

// Simple rate limiter using static data
const staticData = $getWorkflowStaticData('global');
const now = Date.now();
const windowMs = 60000;  // 1 minute window
const maxRequests = 20;  // 20 requests per minute

// Clean old timestamps
staticData.requestTimes = (staticData.requestTimes || [])
  .filter(t => t > now - windowMs);

if (staticData.requestTimes.length >= maxRequests) {
  const waitTime = staticData.requestTimes[0] + windowMs - now;
  await new Promise(r => setTimeout(r, waitTime));
}

staticData.requestTimes.push(now);

Know your provider limits:

Provider	Typical Limits
OpenAI	Varies by tier, typically 500-10,000 RPM
Anthropic	50-4000 RPM depending on tier
Google AI	60 RPM for free tier

Check your specific plan’s limits in your provider dashboard.

Handle quota exhaustion gracefully:

// Check remaining quota before expensive operations
if ($json.error?.code === 'insufficient_quota') {
  return [{
    json: {
      error: 'SERVICE_UNAVAILABLE',
      message: 'AI service temporarily unavailable. Please try again later.',
      retryAfter: 3600  // Suggest retry in 1 hour
    }
  }];
}

For comprehensive rate limiting strategies, see our API rate limits guide.

Agent Hallucination and Accuracy Errors

The agent confidently provides information that’s completely wrong. It claims tools returned data they didn’t. It makes up sources, statistics, or capabilities.

Symptoms

• Responses include fabricated data
• Agent claims to have called tools it didn’t use
• Confident answers that contradict reality
• Made-up sources or references
• Tool results misinterpreted or embellished

Root Causes

Tool returning empty or error. When a tool returns nothing, some agents fill the gap with invented data rather than admitting uncertainty.

No source verification. Without explicit instructions to cite sources, agents present synthesized information as fact.

Prompt encourages guessing. Pressure to “always provide an answer” leads to fabrication when real data isn’t available.

Temperature too high. Higher temperature increases creativity, including creative interpretation of facts.

Fixes

Add explicit anti-hallucination instructions:

ACCURACY REQUIREMENTS:
- Never invent data. If a tool returns no results, say "I couldn't find that information."
- Always cite which tool provided specific data.
- If uncertain, express uncertainty. Say "Based on available data..." not "The answer is..."
- Never claim capabilities you don't have.
- If the user asks for something outside your tools' scope, explain your limitations.

Validate tool results before the agent processes them:

// Validate and label tool responses
const result = $json.toolResult;

if (!result || (Array.isArray(result) && result.length === 0)) {
  return [{
    json: {
      source: "TOOL_RETURNED_EMPTY",
      data: null,
      instruction: "Inform the user no data was found. Do not guess or make up information."
    }
  }];
}

return [{
  json: {
    source: `VERIFIED_FROM_${$json.toolName.toUpperCase()}`,
    data: result,
    instruction: "Use only this verified data in your response."
  }
}];

Require source citations:

RESPONSE FORMAT:
When providing factual information, always indicate the source:
- "According to order_lookup: [information]"
- "The inventory system shows: [information]"
- "I don't have access to that information because [reason]."

Lower temperature for factual responses:

{
  "temperature": 0.3,  // Low creativity for factual accuracy
  "model": "gpt-4"
}

Production Debugging Patterns

The most frustrating scenario: your agent works perfectly in development but fails in production. No obvious errors. Just wrong or missing results under real conditions.

The Production Problem

Production environments differ from testing in ways that break agents:

• Higher load exposes rate limits and timing issues
• Real user input is messier than test cases
• Credential handling differs across instances
• Network latency affects tool response times
• Concurrent executions create race conditions

Debugging Techniques

Correlation ID tracing. Tag every request with a unique ID and include it in all logs:

// At workflow start
const correlationId = `req_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;

// Include in all subsequent operations
console.log(JSON.stringify({
  correlationId,
  stage: 'agent_input',
  data: $json.userMessage,
  timestamp: new Date().toISOString()
}));

Structured logging pattern:

// Create consistent log entries
function logAgentStep(correlationId, step, data) {
  console.log(JSON.stringify({
    correlationId,
    step,
    data: typeof data === 'object' ? data : { message: data },
    timestamp: new Date().toISOString(),
    workflowId: $workflow.id,
    executionId: $execution.id
  }));
}

// Usage
logAgentStep(correlationId, 'tool_selection', { tool: 'order_lookup', reason: 'user asked about order' });
logAgentStep(correlationId, 'tool_result', { success: true, recordCount: 3 });
logAgentStep(correlationId, 'response_generated', { length: response.length });

Error alerting with context:

// Send alerts on agent failures
if ($json.agentError) {
  await $http.post('your-alerting-webhook', {
    body: {
      severity: 'error',
      message: 'AI Agent failure in production',
      correlationId,
      error: $json.agentError,
      input: $json.userMessage?.substring(0, 200),  // Truncate for safety
      timestamp: new Date().toISOString()
    }
  });
}

Circuit Breaker Pattern

When an agent repeatedly fails, stop sending traffic to prevent cascading issues:

// Circuit breaker implementation
const staticData = $getWorkflowStaticData('global');
const breakerKey = 'agent_circuit_breaker';

// Initialize breaker state
if (!staticData[breakerKey]) {
  staticData[breakerKey] = {
    failures: 0,
    lastFailure: null,
    state: 'closed'  // closed = normal, open = blocking, half-open = testing
  };
}

const breaker = staticData[breakerKey];
const cooldownMs = 60000;  // 1 minute cooldown
const failureThreshold = 5;

// Check breaker state
if (breaker.state === 'open') {
  if (Date.now() - breaker.lastFailure > cooldownMs) {
    breaker.state = 'half-open';  // Try one request
  } else {
    // Return fallback response
    return [{
      json: {
        response: "I'm experiencing technical difficulties. Please try again in a moment.",
        fallback: true,
        circuitOpen: true
      }
    }];
  }
}

// After agent execution, update breaker
if ($json.agentError) {
  breaker.failures++;
  breaker.lastFailure = Date.now();

  if (breaker.failures >= failureThreshold) {
    breaker.state = 'open';
  }
} else if (breaker.state === 'half-open') {
  // Success in half-open state, close the breaker
  breaker.state = 'closed';
  breaker.failures = 0;
}

For comprehensive logging setup, see our n8n logging guide. For complex production deployments, our consulting services provide architectural guidance.

Model-Specific Troubleshooting

Different LLM providers have different quirks. A workflow that works with OpenAI might fail with Anthropic or a local model.

OpenAI Issues

Function calling format changes. OpenAI periodically updates their function calling API. Older workflows may break after n8n updates that adopt new formats.

Fix: Check the OpenAI function calling documentation for current format requirements. Update tool descriptions if the format changed.

Model deprecation. Models get deprecated with notice periods. Hardcoded model names eventually fail.

Fix: Use model aliases where available, or implement fallback model selection:

// Fallback model selection
const preferredModel = 'gpt-4';
const fallbackModel = 'gpt-4-turbo';

const modelToUse = $json.modelAvailable?.[preferredModel]
  ? preferredModel
  : fallbackModel;

Anthropic Issues

Tool use syntax differences. Anthropic’s tool use API has different conventions than OpenAI’s function calling.

Fix: Ensure your n8n version supports Anthropic tool use. Check that tool schemas are compatible with both providers if you need portability.

Context handling. Claude models handle long context differently than GPT models. Very long conversations may behave differently.

Fix: Test with realistic conversation lengths. Consider summarizing older context for Claude rather than passing raw history.

Local Models (Ollama)

Capability limitations. Not all local models support function calling. Some have limited context windows or struggle with complex reasoning.

Fix: Verify your chosen model supports tool use. Check the model card for function calling support. Consider using larger models for agent tasks:

// Model capability check
const modelCapabilities = {
  'llama3': { functionCalling: true, contextWindow: 8192 },
  'mistral': { functionCalling: true, contextWindow: 32768 },
  'phi': { functionCalling: false, contextWindow: 2048 }
};

if (!modelCapabilities[$json.model]?.functionCalling) {
  // Fall back to non-agent approach
  return [{ json: { useSimpleChain: true } }];
}

Performance issues. Local models run slower than cloud APIs. Timeout settings that work for OpenAI may be too aggressive.

Fix: Increase timeout values for local model deployments. Consider the hardware requirements for responsive agent execution.

For the full LangChain integration details, see the official n8n LangChain documentation.

Prevention Patterns

The best error is one that never happens. These patterns prevent common AI agent failures before they occur.

Error Handling Architecture

Always enable Continue On Fail. For the AI Agent node and all connected tools, enable this setting so failures don’t crash the entire workflow:

1. Click the node
2. Open Settings
3. Enable Continue On Fail

Implement fallback responses. Every agent path should have a graceful fallback:

// Final node in agent branch
if ($json.error || !$json.response) {
  return [{
    json: {
      response: "I encountered an issue processing your request. " +
                "Please try rephrasing or contact support for help.",
      fallback: true,
      originalError: $json.error?.message
    }
  }];
}
return $input.all();

Use the Error Trigger node. Catch workflow-level failures and respond appropriately. See our Error Trigger node guide for configuration.

Testing Strategies

Unit test each tool independently. Before connecting tools to agents, verify they handle:

• Normal inputs with expected outputs
• Empty or null inputs
• Invalid input formats
• API errors and timeouts

Test edge cases explicitly. Common edge cases that break agents:

• Very long inputs (context overflow)
• Special characters and encoding issues
• Rapid repeated requests (rate limits)
• Concurrent requests (race conditions)

Maintain a regression test suite. Keep a collection of inputs that previously caused failures. Run them after any configuration change.

Monitoring Setup

Track key metrics:

Metric	Warning Threshold
Error rate	> 5%
P95 latency	> 30 seconds
Token cost per request	> 2x baseline
Tool call failures	> 10%

Set up proactive alerting. Don’t wait for users to report problems:

// Execution monitoring
const executionStats = {
  duration: Date.now() - $json.startTime,
  tokensUsed: $json.tokenCount,
  toolsCalled: $json.toolCalls?.length || 0,
  success: !$json.error
};

if (executionStats.duration > 30000 || executionStats.tokensUsed > 5000) {
  // Alert on anomalies
  await sendAlert('Agent performance anomaly', executionStats);
}

For debugging complex workflows, try our workflow debugger tool.

Quick Reference: Error Message Lookup

Use this table to quickly find solutions for common AI agent error messages.

Error Message	Likely Cause	Solution Section
"Could not parse LLM output"	Agent reasoning breaks JSON format	Output Parsing Failures
"Max iterations exceeded"	Agent stuck in reasoning loop	Infinite Loop Errors
"Tool not found" / "No tool with name"	Tool misconfiguration or description issue	Tool Selection Errors
429 Too Many Requests	API rate limit exceeded	Rate Limiting and API Errors
"Rate limit exceeded"	Provider throttling requests	Rate Limiting and API Errors
"Context window exceeded"	Conversation history too long	Memory and Context Errors
"insufficient_quota"	API credits exhausted	Rate Limiting and API Errors
"Authentication failed" / 401 Unauthorized	Invalid or expired API credentials	Model-Specific Troubleshooting
Agent responds without using tools	Vague tool descriptions or too many tools	Tool Selection Errors
Agent returns empty or null response	Tool failure or hallucination	Agent Hallucination Errors
Execution runs for minutes	Infinite loop or no completion criteria	Infinite Loop Errors
Works in testing, fails in production	Environment differences	Production Debugging Patterns
Agent forgets previous messages	Session ID or memory misconfiguration	Memory and Context Errors

Tip: Use Ctrl+F (or Cmd+F on Mac) to search for your exact error message on this page.

Frequently Asked Questions

Why does my AI agent work in testing but fail in production?

Production environments differ in ways that expose hidden issues. Common causes:

Load differences. Testing uses one request at a time. Production sends concurrent requests that trigger rate limits, exhaust connections, or create race conditions.

Input variety. Test cases are clean and predictable. Real users send messy, unexpected inputs that break assumptions in your prompts or tools.

Credential scope. Development credentials often have different permissions than production. Verify your production API keys have all required access.

Timing sensitivity. Local testing has low latency. Production network delays can cause timeouts or change tool response ordering.

Fix approach: Add comprehensive logging with correlation IDs. Compare production logs against successful test executions to identify where behavior diverges.

---

How do I stop my agent from using too many tokens?

Token costs multiply when agents run inefficiently. Apply these controls:

Limit memory window. Use Window Buffer Memory with a small window (5-10 messages). Old context drops off, preventing unbounded growth.

Set iteration limits. Configure maximum reasoning iterations in your chat model settings if available. This prevents infinite loops.

Reduce tool descriptions. Each tool description is sent to the LLM on every turn. Trim descriptions to essential information. Remove examples if the tool is straightforward.

Use appropriate models. Smaller, cheaper models handle simple tasks well. Reserve expensive models for complex reasoning.

Cache common queries. If users frequently ask similar questions, cache responses to skip LLM calls entirely.

---

Why does my agent ignore the tools I connected?

Tool selection depends on descriptions matching user intent. Common fixes:

Check descriptions are specific. Replace “handles data” with “looks up customer orders by order ID or email address.”

Verify tool connections. In the n8n UI, confirm tools appear connected to the agent node. Sometimes connections display incorrectly.

Add tool guidance to the system prompt. Explicitly tell the agent when to use each tool:

TOOL USAGE:
For order questions, ALWAYS use order_lookup before responding.
For product availability, use inventory_check.

Test with direct instructions. Ask the agent: “Use the order_lookup tool to find order 12345.” If this works but natural questions don’t, the issue is description matching.

Reduce tool count. With too many tools, the agent may default to responding without tools rather than choosing. Consolidate or split into multiple specialized agents.

---

How can I debug what my AI agent is thinking?

n8n provides visibility into agent reasoning:

1. Go to Executions in the n8n sidebar
2. Click on the execution you want to inspect
3. Click on the AI Agent node in the execution view
4. Expand the Output panel

The output shows:

• The input received by the agent
• Each reasoning step with tool decisions
• Tool call parameters and results
• The final generated response

For production debugging, add a Code node before the agent that logs:

console.log(JSON.stringify({
  timestamp: new Date().toISOString(),
  sessionId: $json.sessionId,
  userInput: $json.message,
  memoryLoaded: $json.chatHistory?.length || 0
}));

Review these logs alongside execution data to understand the complete context the agent received.

---

What’s the best way to handle API rate limits with agents?

Implement multiple layers of protection:

Preemptive throttling. Track requests and delay before hitting limits rather than after:

const requestsInLastMinute = countRecentRequests();
if (requestsInLastMinute > 50) {
  await sleep(2000);  // Slow down proactively
}

Exponential backoff on 429. When you hit limits, wait progressively longer:

const backoffMs = Math.min(1000 * Math.pow(2, retryCount), 30000);
await sleep(backoffMs);

Queue instead of parallel. For high-volume workflows, process requests sequentially rather than in parallel. Use n8n’s queue mode for distributed processing.

Monitor quotas. Track usage against your plan limits. Alert before hitting caps, not after.

Fallback gracefully. When limits are hit, provide a useful response rather than crashing:

if (error.statusCode === 429) {
  return [{
    json: {
      response: "I'm currently handling many requests. Please try again in a moment.",
      retryAfter: 60
    }
  }];
}

For detailed rate limiting implementation, see our API rate limits guide.