Fix: Sub-Agent Timeout or Hang

Error Message:

"Sub-agent execution timed out" "Waiting for agent..." (spinning indefinitely) "Partial results received — 2 of 5 agents completed" "Agent exceeded maximum step count"

What This Error Means

Claude Cowork can split complex tasks into parallel sub-tasks, each handled by a sub-agent — a separate instance of the model with its own context window and tool access. You might ask Claude to "research these 10 companies" and it spawns 10 sub-agents, each investigating one company. This is powerful, but each sub-agent is an independent process with its own timeout, token budget, and tool call limit.

When a sub-agent times out or hangs, it means one or more of those independent processes didn't finish within the allowed limits. The parent task either waits forever (a hang), returns partial results, or throws an explicit timeout error. The root cause is almost always in the sub-agent's behavior, not in Claude's core infrastructure.

Root Cause Analysis

The most common cause is an infinite loop. A sub-agent gets a task it can't fully solve — maybe the information doesn't exist, or the search keeps returning irrelevant results — and it keeps trying the same approach over and over. Each iteration consumes tool calls and tokens without making progress. Eventually it hits the step limit or the timeout, and the parent task reports failure. This is especially common with research tasks where the agent is looking for specific data that simply isn't available in the sources it has access to. The agent doesn't know the data doesn't exist, so it keeps searching.

A second cause is rate limiting. When you spawn many sub-agents simultaneously, each one makes API calls. If you launch 10 agents and each makes 5 tool calls in the first few seconds, that's 50 API requests in a short window. Your plan's rate limit kicks in, and some agents get throttled. They sit waiting for rate limit windows to reset, which eats into their timeout budget. By the time the rate limit clears, there's not enough time left to finish the task, and they time out. This is silent — you won't see a "rate limited" error, just a timeout.

A third cause is network instability. Sub-agents that call external tools (web search, MCP servers, database queries) are vulnerable to network hiccups. A brief connectivity drop causes a tool call to hang, and the sub-agent waits for a response that never comes. If the sub-agent doesn't have internal retry logic, it sits there until the timeout fires. This is intermittent and hard to reproduce, which makes it frustrating to diagnose.

Real-World Example

A user asked Claude to research 12 competitors simultaneously — for each one, find their pricing, funding history, and key product features. Claude spawned 12 sub-agents. Three of the competitors were very small companies with almost no online presence. Those three sub-agents kept searching, trying different queries, and hitting dead ends. They each burned through 15+ search steps without finding pricing data, then timed out. The other nine completed successfully. The user saw "Partial results received — 9 of 12 agents completed" and didn't know which three failed or why. The fix: the user re-ran the task for just the three missing companies, with an explicit instruction to stop searching if no pricing data was found within 3 attempts.

Step-by-Step Fix

1. Reduce Parallelism

The easiest fix. Fewer concurrent agents means less rate limit pressure and easier debugging.

  • Instead of: "Research these 20 companies at once."
  • Try: "Research the first 5 companies. Wait for results, then do the next 5."

Most plans handle 3–5 concurrent sub-agents smoothly. Going above 10 simultaneously is where timeouts become frequent.

2. Add Explicit Stop Conditions to Your Prompt

Sub-agents will keep searching unless you tell them when to stop. Add a "time budget" or step limit directly in your prompt.

Example prompt:

"Research this company's pricing. If you cannot find pricing information after 3 search attempts, stop and report 'Pricing not publicly available.' Do not keep searching beyond 3 attempts."

This prevents the infinite-loop pattern. The sub-agent either finds the answer quickly or gives up gracefully, and you get a clear status instead of a timeout.

3. Check the Agent Logs

You can see what each sub-agent is actually doing.

  1. Open the Console/Logs panel in Cowork (shortcut: Cmd+Opt+L on macOS, Ctrl+Alt+L on Windows).
  2. Look for the sub-agent IDs that failed or are still running.
  3. Check the tool call sequence. Is the agent calling the same search tool repeatedly with slightly different queries? That's a loop.
  4. Is the agent stuck on a single tool call that never returned? That's a network or external service issue.
  5. If it's looping, kill the task and refine your prompt with a stop condition (see step 2).
  6. If it's stuck on a tool call, check whether the external service (MCP server, web search endpoint) is responsive.

4. Switch Models for Difficult Sub-Tasks

Faster, smaller models (like Haiku) are cheaper and quicker but can get confused on complex reasoning tasks — they may loop more often or fail to recognize when a search is unproductive. Larger models (like Opus or Sonnet) handle ambiguity better and are more likely to recognize a dead end.

  • In your prompt, specify: "Use Opus for this sub-task" (if your plan allows model selection).
  • Or, set the default sub-agent model in Settings → Agents → Default Model.

This costs more tokens per agent but reduces timeout frequency for hard tasks.

5. Increase the Timeout Threshold

If your tasks genuinely need more time (large codebase analysis, multi-step research), you can adjust the timeout.

  • Go to Settings → Agents → Timeout.
  • The default is usually 120 seconds. Increase to 300 seconds for complex tasks.
  • Be aware: longer timeouts mean you wait longer before learning that an agent failed.

Common Pitfalls

  • Spawning too many agents without a stop condition. This is the #1 cause of timeouts. Always include a "stop after N attempts" instruction in research prompts.
  • Assuming all sub-agents will succeed. Design your workflow to handle partial results. If 8 of 10 agents complete, use those 8 results and re-run the 2 failures separately.
  • Ignoring the token overhead. Each sub-agent consumes a minimum of ~12,000 tokens per tool call in overhead (system prompt, context setup, tool definitions). Spawning 20 agents means 240,000 tokens before any real work starts — which can itself blow the context window or rate limits.
  • Not checking logs when agents fail. The logs tell you exactly why an agent timed out. Skipping this step means you're guessing at the fix.
  • Using Haiku for nuanced research. Haiku is great for simple, well-defined tasks but tends to loop on ambiguous research. Reserve it for straightforward lookups.

Prevention Checklist

  • Always include a stop condition in sub-agent prompts ("stop after 3 attempts," "report 'not found' if no results").
  • Keep concurrent sub-agent count at or below 5 unless you have a specific reason to go higher.
  • Design workflows to handle partial results gracefully — don't assume 100% completion.
  • Check the agent logs whenever a timeout occurs to identify the specific failure pattern.
  • Use larger models (Sonnet or Opus) for complex or ambiguous sub-tasks; reserve Haiku for simple lookups.
  • Monitor token usage — sub-agent overhead adds up fast with many agents.
  • For tasks involving external tools, verify those tools are responsive before spawning agents that depend on them.