The agent is nearing the end of its context window and has b

Error message

The agent is nearing the end of its context window and has been stopped. You can prompt the thread again to have the agent wrap up or hand off its work.

What it means

When a subagent nears its context-window limit, the run is cancelled via thread.cancel and this error is returned so the parent knows work stopped early. The message tells the user they can re-prompt the thread so the agent wraps up or hands off its work.

Source

Thrown at crates/agent/src/agent.rs:3423

                                .iter()
                                .filter_map(|c| match c {
                                    AgentMessageContent::Text(text) => Some(text.as_str()),
                                    _ => None,
                                })
                                .join("\n\n");
                            if content.is_empty() {
                                None
                            } else {
                                Some( content)
                            }
                        })
                        .context("No response from subagent")
                }),
                SubagentPromptResult::Cancelled => Err(anyhow!("User canceled")),
                SubagentPromptResult::Error(message) => Err(anyhow!("{message}")),
                SubagentPromptResult::ContextWindowWarning => {
                    thread.update(cx, |thread, cx| thread.cancel(cx)).await;
                    Err(anyhow!(
                        "The agent is nearing the end of its context window and has been \
                         stopped. You can prompt the thread again to have the agent wrap up \
                         or hand off its work."
                    ))
                }
            };

            parent_thread
                .update(cx, |parent_thread, cx| {
                    parent_thread.unregister_running_subagent(&subagent_session_id, cx)
                })
                .ok();

            result
        })
    }
}

View on GitHub (pinned to bc538def45)

Solutions

Re-prompt the thread so the agent summarizes and hands off its state, as the message suggests.
Split the task into smaller subagent runs and hand in less context (fewer files, tighter prompts).
Use a model with a larger context window for subagents that routinely run long.

Defensive patterns

Strategy: try-catch

Try / catch

match subagent_prompt_result {
    Err(e) if e.to_string().contains("nearing the end of its context window") => {
        // offer the user a one-click re-prompt so the agent wraps up
    }
    Err(e) => return Err(e),
    Ok(output) => { /* use output */ }
}

Prevention

Give subagents narrower tasks and less pasted context.
Pick larger-context models for tool-heavy subagent work.
Watch token usage and hand off before the threshold trips.

When it happens

Trigger: Subagent context usage crossing the warning threshold during a run, triggering the built-in stop-before-overflow behavior.

Common situations: Large-file analysis, long tool-heavy tasks, or subagents running on small-context models.

Related errors

AI-assisted analysis of zed-industries/zed@bc538def45 (2026-08-16). Data as JSON: /api/errors/5f6ddbc32c7a18fe. Report an issue: GitHub.