Agents Troubleshooting Task Tool FAQ

Agent Troubleshooting Guide: Common Issues and Solutions

Common problems when using Claude Code Agents and how to fix them. Covering timeouts, incomplete results, parallel execution failures, and more.

January 15, 2026 • 12 min read • By Claude World

When using Claude Code’s Agent tool (called the Task tool before v2.1.63; the Task({...}) examples below use that still-supported alias) and agents, you might encounter some common issues. This guide covers the most frequent problems and their solutions.

Updated October 21, 2026: Refreshed for Claude Code v2.1.305 — subagents now start in the background by default, TaskOutput is gone (v2.1.277), the built-in Explore agent runs on your main model instead of Haiku, haiku now means Haiku 5.5, and the model, concurrency-limit and error advice reflects current behavior.

Common Issue Categories

CategoryTypical SymptomsCommon Causes
Startup IssuesAgent won’t start, fails immediatelyPermissions, config, path errors
Timeout IssuesAgent takes too longContext too large, task complex, resource limits
Result IssuesResults incomplete or incorrectVague prompts, insufficient context
Parallel IssuesAgents not running in parallelWrong call pattern, resource contention
Performance IssuesSlow, high memory usageModel choice, task design

Issue 1: Agent Won’t Start or Fails Immediately

Symptoms

Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: "Explore auth module"
})
// Error: "Failed to start agent" or immediate error

Possible Causes & Solutions

Cause 1: Wrong Working Directory

Problem: Current directory is not project root.

Solution:

# Verify you're in project root
pwd
# Should show project path, e.g., /Users/you/projects/my-app

# If not, navigate to correct directory
cd /path/to/your/project

Cause 2: Git Repository Not Initialized

Problem: Some agent features require git history.

Solution:

# Initialize git repo
git init
git add .
git commit -m "Initial commit"

Cause 3: File Permissions

Problem: Claude Code can’t read project files.

Solution:

# Check file permissions
ls -la

# Fix if needed
chmod -R +r ./

Cause 4: Model Not Available

Problem: The requested model isn’t available to you — your organization’s availableModels allowlist excludes it, your cloud provider account hasn’t enabled it, or your Claude Code is older than the model requires (Opus 5.5 needs v2.1.280+, Sonnet 5.5 v2.1.284+, Haiku 5.5 v2.1.293+). Opus itself needs no special access: Opus 5.5 is the default model on Pro, Max, Team, Enterprise and the Anthropic API.

Solution: If the error says your version doesn’t support the model, run claude update. For a model your organization restricts, Claude Code runs the subagent on a permitted model instead and shows a notice; run /tasks to see which model each subagent actually uses.

// Request a model your plan or provider allows,
// or omit `model` to use the main conversation's model
Task({
  subagent_type: "general-purpose",
  model: "sonnet",  // Sonnet 5.5 on the Anthropic API
  prompt: "Your task"
})

Issue 2: Agent Execution Timeout

Symptoms

Agent takes longer than expected (e.g., over 2 minutes) without returning results.

Possible Causes & Solutions

Cause 1: Task Scope Too Broad

Problem: Prompt too vague, causing agent to scan entire project.

Bad Example:

Task({
  subagent_type: "Explore",
  prompt: "Analyze everything about this codebase"  // Too broad
})

Good Example:

Task({
  subagent_type: "Explore",
  prompt: "Explore authentication module (thoroughness: medium). Find JWT handling and session management."
})

Cause 2: Using Too High Thoroughness

Problem: very thorough level appropriate for small scope, too slow for entire project.

Solution:

// Use medium or quick for large scope
Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: "Explore entire codebase structure (thoroughness: quick)"
})

// Use very thorough for small scope
Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: "Deep dive into auth/login.ts (thoroughness: very thorough)"
})

Cause 3: Context Too Large

Problem: Agent needs to process too many files.

Solution: Split tasks

// Bad: Process all modules at once
Task({ prompt: "Analyze all API endpoints" })

// Good: Process separately
Task({ prompt: "Analyze user-related API endpoints" })
Task({ prompt: "Analyze payment-related API endpoints" })
Task({ prompt: "Analyze admin-related API endpoints" })

Cause 4: Using Background Task Without Checking

Problem: Agent running in background, you think it timed out. With nothing configured, subagents Claude spawns from your main conversation start in the background (interactive terminal sessions since v2.1.232), so a quiet transcript usually means the agent is still working.

Solution: Run /tasks to see running and recently finished subagents and the model each one uses. The result reaches Claude as a completion notification in a later turn; if you ask about progress before then, Claude reports that the agent is still running.

// Start background task
Task({
  subagent_type: "security-auditor",
  model: "sonnet",
  prompt: "Comprehensive security audit",
  run_in_background: true
})

// TaskOutput was removed in v2.1.277: the result arrives
// as a completion notification. Check progress with /tasks;
// stop a run with x in /tasks (Claude uses TaskStop).

Issue 3: Agent Returns Incomplete Results

Symptoms

Agent returns results missing expected content, or answers only part of your question.

Possible Causes & Solutions

Cause 1: Vague Prompt

Problem: Agent unsure what to look for.

Bad Example:

Task({
  prompt: "Look at the auth code and tell me what you think"  // Too vague
})

Good Example:

Task({
  prompt: `
    Analyze authentication module (src/auth/).
    Report specifically on:
    1. JWT secret storage (how is it stored?)
    2. Session management (what strategy?)
    3. Password hashing (which algorithm?)

    Format as a bulleted list.
  `
})

Cause 2: Too Many Questions in One Request

Problem: Prompt contains too many requests, agent missed some.

Solution: Split into multiple requests

// Bad: Ask everything at once
Task({
  prompt: "Analyze auth, payments, user management, admin panel, and reporting"
})

// Good: Ask separately
Task({ prompt: "Analyze authentication system" })
Task({ prompt: "Analyze payment system" })
Task({ prompt: "Analyze user management" })

Cause 3: Insufficient Context

Problem: Agent doesn’t have enough context to understand your needs.

Solution: Provide more background

Task({
  prompt: `
    Context: We're migrating from REST to GraphQL.
    Current state: All endpoints are in src/api/v1/

    Task: Find all REST endpoints and list which ones still need migration.
  `
})

Cause 4: Wrong Exploration Scope

Problem: Explore agent thoroughness level inappropriate.

Solution:

// Use quick for quick overview
Task({
  subagent_type: "Explore",
  prompt: "List all files in src/auth/ (thoroughness: quick)"
})

// Use medium or very thorough for deep analysis
Task({
  subagent_type: "Explore",
  prompt: "Analyze authentication flow in detail (thoroughness: medium)"
})

Issue 4: Parallel Agents Not Running in Parallel

Symptoms

You launched multiple agents, but they seem to run sequentially instead of in parallel.

Possible Causes & Solutions

Cause 1: Wrong Call Pattern

Problem: Calling Task sequentially in a loop, not simultaneously. This only serializes agents that run in the foreground, where Claude waits for each result before its next call. With nothing configured, subagents Claude spawns from your main conversation now start in the background and run concurrently (interactive terminal sessions since v2.1.232); Claude can still wait for them in claude -p and the Agent SDK, or in interactive sessions once you turn fork mode off with CLAUDE_CODE_FORK_SUBAGENT=0, and it waits for every subagent when CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 is set.

Bad Example:

// This runs sequentially
const agents = ['auth', 'payment', 'user']
for (const topic of agents) {
  Task({ prompt: `Analyze ${topic}` })  // Sequential!
}

Good Example:

// This runs in parallel
Task({ prompt: "Analyze auth" })
Task({ prompt: "Analyze payment" })
Task({ prompt: "Analyze user" })
// All launched simultaneously, run in parallel

Cause 2: Resource Contention

Problem: Too many agents running simultaneously, causing resource exhaustion. Claude Code also refuses to spawn more once 20 subagents are running in a session (Concurrent subagent limit reached; change the cap with CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS), and every subagent draws on the same usage limits as your main conversation.

Solution: Limit parallel count

// Bad: 10 parallel agents
for (let i = 0; i < 10; i++) {
  Task({ prompt: `Task ${i}` })
}

// Good: Batch execution (3-5 per batch)
// Batch 1
Task({ prompt: "Task 1" })
Task({ prompt: "Task 2" })
Task({ prompt: "Task 3" })
// Wait for completion, then Batch 2
Task({ prompt: "Task 4" })
Task({ prompt: "Task 5" })
Task({ prompt: "Task 6" })

Cause 3: Agents Have Dependencies

Problem: Later agents depend on earlier agent results.

Solution: Phased execution

// Phase 1: Parallel exploration (independent)
Task({ prompt: "Map file structure" })
Task({ prompt: "Find API endpoints" })
Task({ prompt: "List database models" })
// Wait for completion

// Phase 2: Use Phase 1 results
Task({ prompt: "Based on structure found, analyze auth flow" })

Issue 5: Poor Agent Performance or High Memory Usage

Symptoms

Agent runs slowly, or system memory usage spikes.

Possible Causes & Solutions

Cause 1: Using Wrong Model

Problem: Simple task using expensive model.

Solution: Choose appropriate model

// Bad: Simple search with Opus
Task({
  subagent_type: "Explore",
  model: "opus",  // Too expensive
  prompt: "Find login function"
})

// Good: Simple search with Haiku
Task({
  subagent_type: "Explore",
  model: "haiku",  // Fast and cheap
  prompt: "Find login function (thoroughness: quick)"
})

Explore no longer defaults to Haiku: since v2.1.198 the built-in Explore agent runs on your main conversation’s model — Opus 5.5 by default on Pro, Max, Team, Enterprise and the Anthropic API (when the main session runs Fable on a Claude subscription or Anthropic Console account, Explore uses Opus instead). Pass model: "haiku" as above, or define your own Explore agent with model: haiku, to keep searches cheap. On the Anthropic API haiku now resolves to Haiku 5.5; on Amazon Bedrock, Google Cloud’s Agent Platform, Microsoft Foundry and Claude Platform on AWS it is still Haiku 4.5.

Cause 2: Context Overload

Problem: Agent loaded too many unnecessary files.

Solution: Narrow scope

// Bad: Explore entire monorepo
Task({
  prompt: "Analyze entire monorepo"
})

// Good: Focus on specific package
Task({
  prompt: "Analyze packages/auth/ only"
})

Cause 3: Duplicate Work

Problem: Multiple agents analyzing same files repeatedly.

Solution: Coordinate tasks

// Bad: Repeated exploration
Task({ prompt: "Analyze auth for security" })
Task({ prompt: "Analyze auth for performance" })
Task({ prompt: "Analyze auth for code quality" })
// Three times reading same files

// Good: Divide work
Task({ prompt: "Explore auth module (thoroughness: medium)" })
// Then use results for different analyses

Cause 4: Not Using Explore Agent

Problem: Using general-purpose agent for file search.

Solution:

// Bad: File search with general-purpose
Task({
  subagent_type: "general-purpose",
  prompt: "Find all files with 'auth' in the name"
})

// Good: File search with Explore agent
Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: "Find all auth-related files (thoroughness: quick)"
})

Issue 6: Choosing Wrong Agent Type

Symptoms

Results don’t match expectations, or agent seems unsuitable for task.

Agent Selection Guide

TaskCorrect AgentWrong Agent
File searchExplore (with model: "haiku")general-purpose
Code reviewcode-reviewerExplore
Security auditsecurity-auditorcode-reviewer
Test analysistest-runnergeneral-purpose
DebuggingdebuggerExplore
Refactoringrefactor-assistantgeneral-purpose

Only Explore, Plan and general-purpose (plus a few helpers) are built in. code-reviewer, security-auditor, test-runner, debugger and refactor-assistant are custom agents you define in .claude/agents/ or ~/.claude/agents/, or install from a plugin. If Claude can’t find one, check its frontmatter: Claude Code skips an agent file without any message in the session when it has no name, has a name but no description, or its YAML doesn’t parse. claude plugin validate .claude/agents flags frontmatter that doesn’t parse, and claude --debug records most skips in the debug log. For reviews, Claude Code also ships /code-review (alias /review) and /security-review.

Example

// ❌ Wrong: Security audit with Explore
Task({
  subagent_type: "Explore",
  prompt: "Check for security vulnerabilities"
})

// ✅ Correct: Security audit with security-auditor
Task({
  subagent_type: "security-auditor",
  model: "sonnet",
  prompt: "Audit for security vulnerabilities"
})

Issue 7: Agent Results Hard to Understand

Symptoms

Agent returns results in messy format, or difficult to integrate into workflow.

Solutions

Solution 1: Request Specific Format

Task({
  prompt: `
    Analyze the authentication module.

    Format your response as:
    ## Overview
    [2-3 sentences]

    ## Findings
    - [Bullet point 1]
    - [Bullet point 2]

    ## Recommendations
    1. [Recommendation 1]
    2. [Recommendation 2]
  `
})

Solution 2: Request JSON Output

Task({
  prompt: `
    List all API endpoints.

    Respond in this JSON format:
    {
      "endpoints": [
        {"path": "/api/users", "method": "GET", "auth": true},
        {"path": "/api/users", "method": "POST", "auth": true}
      ]
    }
  `
})

Solution 3: Phased Result Collection

// Phase 1: Collect raw data
const rawData = Task({ prompt: "List all endpoints" })

// Phase 2: Format
Task({
  prompt: `
    Format this data as a markdown table:
    ${rawData}

    Columns: Path, Method, Auth Required, Description
  `
})

Diagnostic Tools & Techniques

Technique 1: Stepwise Simplification

If agent fails, gradually simplify task:

// Step 1: Minimal viable task
Task({ prompt: "List files in src/" })

// Step 2: Slightly more complex
Task({ prompt: "List files in src/auth/" })

// Step 3: Full task
Task({ prompt: "Analyze auth module structure" })

Technique 2: Use Verbose Mode

When diagnosing issues, add more context:

Task({
  prompt: `
    [VERBOSE MODE]
    I'm trying to understand why X fails.

    Please:
    1. List all files you examined
    2. Show your reasoning step-by-step
    3. Report any errors encountered

    Task: [your actual task]
  `
})

Technique 3: Comparison Testing

Compare results using different agents simultaneously:

// Agent 1
const result1 = Task({
  subagent_type: "Explore",
  prompt: "Find all auth functions"
})

// Agent 2
const result2 = Task({
  subagent_type: "general-purpose",
  prompt: "Find all auth functions"
})

// Compare result differences

When to Seek Help

If above solutions don’t solve your problem:

  1. Check Claude Code Version:

    claude --version

    Ensure you’re using the latest version.

  2. Check GitHub Issues: https://github.com/anthropics/claude-code/issues

  3. Join Community:

  4. Report Bug: When reporting, include:

    • Claude Code version
    • Operating system
    • Full error message
    • Reproduction steps
    • Minimal reproducible example

Quick Reference: Common Error Codes

Error CodeMeaningSolution
ENOENTPath not foundCheck file path is correct
EACCESPermission deniedCheck file permissions
ETIMEDOUTExecution timeoutReduce task scope or lower thoroughness
ENOMEMOut of memoryReduce number of parallel agents
ECONNREFUSEDAPI connection failedCheck network connection and API Key
Agent '…' would be spawned with zero toolsNo entry in the agent’s tools list matched a usable toolFix the tool names, or remove tools to inherit the default set
Concurrent subagent limit reached20 subagents already running (default cap)Wait for some to finish, or raise CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS
Agent terminated early due to an API errorA usage limit or server error stopped the subagentFix the underlying error, then ask Claude to retry or resume the agent

Preventive Best Practices

Best way to avoid problems:

  1. Start with small tasks: Test simple tasks first, confirm agent works
  2. Use appropriate models: Haiku for search (Haiku 5.5 on the Anthropic API), Sonnet 5.5 for everyday implementation, Opus 5.5 (the default) for hard reasoning
  3. Keep prompts clear: Be specific about what you want
  4. Work in phases: Explore → Analyze → Implement
  5. Monitor resources: Watch memory and CPU usage
  6. Save work results: Commit to git regularly, avoid losing progress

Encountered other issues? Ask in the #help channel on Discord, the community is happy to help!