Agent Troubleshooting Guide: Common Issues and Solutions

When using Claude Code’s Task tool and agents, you might encounter some common issues. This guide covers the most frequent problems and their solutions.

Common Issue Categories

Category	Typical Symptoms	Common Causes
Startup Issues	Agent won’t start, fails immediately	Permissions, config, path errors
Timeout Issues	Agent takes too long	Context too large, task complex, resource limits
Result Issues	Results incomplete or incorrect	Vague prompts, insufficient context
Parallel Issues	Agents not running in parallel	Wrong call pattern, resource contention
Performance Issues	Slow, high memory usage	Model 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: Specified model unavailable (e.g., Opus requires special access).

Solution:

// Use Sonnet instead (default available)
Task({
  subagent_type: "general-purpose",
  model: "sonnet",  // not "opus"
  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.

Solution:

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

// Check results later
TaskOutput({ task_id: taskId, block: true })

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.

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.

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)"
})

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

Task	Correct Agent	Wrong Agent
File search	`Explore` (haiku)	`general-purpose`
Code review	`code-reviewer`	`Explore`
Security audit	`security-auditor`	`code-reviewer`
Test analysis	`test-runner`	`general-purpose`
Debugging	`debugger`	`Explore`
Refactoring	`refactor-assistant`	`general-purpose`

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:

Check Claude Code Version:
```
claude --version
```
Ensure you’re using the latest version.
Check GitHub Issues: https://github.com/anthropics/claude-code/issues
Join Community:
- Claude World Discord
- #help channel
Report Bug: When reporting, include:
- Claude Code version
- Operating system
- Full error message
- Reproduction steps
- Minimal reproducible example

Quick Reference: Common Error Codes

Error Code	Meaning	Solution
`ENOSP`	Path not found	Check file path is correct
`EACCES`	Permission denied	Check file permissions
`ETIMEDOUT`	Execution timeout	Reduce task scope or lower thoroughness
`ENOMEM`	Out of memory	Reduce number of parallel agents
`ECONNREFUSED`	API connection failed	Check network connection and API Key

Preventive Best Practices

Best way to avoid problems:

Start with small tasks: Test simple tasks first, confirm agent works
Use appropriate models: Haiku for search, Sonnet for reasoning
Keep prompts clear: Be specific about what you want
Work in phases: Explore → Analyze → Implement
Monitor resources: Watch memory and CPU usage
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!