Claude Code Subagent Spawn Limit — Fix (2026)

The Error

Cannot spawn subagent: maximum agent depth reached (3/3)

The Fix

# Restructure your CLAUDE.md to use sequential tasks instead of nested agents
# Replace nested agent calls with direct tool usage in the parent agent
# In your CLAUDE.md, add:
echo "Prefer sequential tool calls over nested agent spawning" >> CLAUDE.md

Why This Works

Claude Code enforces a maximum nesting depth of 3 levels to prevent infinite recursion and resource exhaustion. When an agent spawns a subagent that spawns another subagent, the third level hits the ceiling. Flattening the task structure keeps execution within bounds.

If That Doesn’t Work

# Break the work into separate top-level invocations
claude "Do step 1: analyze the codebase structure"
claude "Do step 2: implement changes based on analysis"
claude "Do step 3: verify and test the implementation"

Run each step as an independent session so each starts at depth 0. You can pass context between sessions using files — write analysis results to a JSON file in step 1, then reference that file in step 2 to maintain continuity without requiring nested agents.

Prevention

Add to your CLAUDE.md:

Never design workflows requiring more than 2 levels of agent nesting. Use sequential tool calls or break into separate top-level sessions instead of spawning deeply nested subagents.

See Also

This fix also applies if you see these related error messages:

  • SyntaxError: Unexpected token in JSON at position 0
  • JSON.parse: unexpected character at line 1 column 1
  • Error: invalid JSON response from API
  • SessionError: session expired
  • Error: session state corrupted

Frequently Asked Questions

Why does JSON parsing fail on API responses?

JSON parse failures on API responses typically indicate a network issue where an intermediate proxy returned an HTML error page instead of JSON. Check the raw response by enabling debug logging with CLAUDE_LOG_LEVEL=debug to see the actual content received.

How do I fix corrupted JSON config files?

Open the file in a text editor and look for common issues: trailing commas, missing quotes, or truncated content (from a crash during write). Use python3 -m json.tool < file.json to validate and identify the exact parse error location.

Can Claude Code handle JSON files with comments?

Standard JSON does not support comments. If your project uses JSONC (JSON with Comments), Claude Code handles it when reading via tools. For configuration files like tsconfig.json that support JSONC, Claude Code strips comments before parsing.

How long do Claude Code sessions last?

Sessions persist until you close the terminal, exit Claude Code, or hit the context window limit. There is no hard time limit, but very long sessions (more than 100 messages) may experience context compression that reduces earlier message detail.

Try it: Paste your error into our Error Diagnostic for an instant fix.

Implementation Details

When working with this in Claude Code, pay attention to these practical details:

Project configuration. Add specific instructions to your CLAUDE.md file describing how your project handles this area. Include file paths, naming conventions, and any patterns that differ from common defaults. Claude Code reads CLAUDE.md at the start of every session and uses it to guide all operations.

Testing the setup. After configuration, verify everything works by running a simple test task. Ask Claude Code to perform a read-only operation first (like listing files or reading a config) before moving to write operations. This confirms that permissions, paths, and tools are all correctly configured.

Monitoring and iteration. Track your results over several sessions. If Claude Code consistently makes the same mistake, the fix is usually a more specific CLAUDE.md instruction. If it makes different mistakes each time, the issue is likely in the project setup or toolchain configuration.

Troubleshooting Checklist

When something does not work as expected, check these items in order:

  1. CLAUDE.md exists at the project root — run ls -la CLAUDE.md to verify
  2. Node.js version is 18+ — run node --version to check
  3. API key is set — run echo $ANTHROPIC_API_KEY | head -c 10 to verify (shows first 10 characters only)
  4. Disk space is available — run df -h . to check
  5. Network can reach the API — run curl -s -o /dev/null -w "%{http_code}" https://api.anthropic.com (should return 401 without auth, meaning the server is reachable)
  6. No conflicting processes — run ps aux | grep claude | grep -v grep to check for stale sessions