The agent reached the maximum number of allowed requests…

Error message

The agent reached the maximum number of allowed requests between user turns. Try prompting again.

What it means

Mapped from ACP StopReason::MaxTurnRequests: the agent exceeded the maximum number of model requests permitted within a single user turn (a turn-request cap that prevents unbounded agentic loops). The run is stopped and this error is returned to the parent thread instead of a final message.

Solutions

Give the agent a narrower, more specific task so it completes within fewer requests
Re-prompt the thread to continue from where it stopped, as the message suggests
Split the work into multiple sequential turns with intermediate checkpoints
Reduce tool-call churn by providing the needed context/files up front in the prompt

Example fix

// before: unbounded task
thread.send("Fix every failing test in the workspace");

// after: bounded task
thread.send("Fix only the failing tests in crates/agent/src/tests/agent_tests.rs");

Defensive patterns

Strategy: retry

Validate before calling

// avoid dispatching tasks likely to need many tool calls:
// keep prompt scope to a single file/module when possible

Try / catch

match subagent_result {
    Err(e) if e.to_string().contains("maximum number of allowed requests") => {
        // re-prompt the thread to continue, or split the task and retry
    }
    other => other?,
}

Prevention

Scope each agent turn to a bounded, well-defined task
Provide needed file contents in the prompt to cut down tool-call round trips
Checkpoint progress across turns instead of one giant task
Watch for tool-failure retry loops that burn the request budget

When it happens

Trigger: A subagent enters a long chain of tool calls (search, read, edit) requiring more model round-trips than the per-turn limit allows, so the backend ends the turn with stop_reason=MaxTurnRequests.

Common situations: Broad, open-ended tasks like 'fix all the tests' or 'refactor this crate' that spiral into dozens of tool invocations; tool failures causing retry loops; agents stuck re-reading the same files.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

AI-assisted analysis of zed-industries/zed@916fc2b8cb (2026-09-19). Data as JSON: /api/errors/5353004dd2349061. Report an issue: GitHub.

Appendix: source

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

                        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."
                        ))
                    }
                }
            };
            let discard_partial_output = matches!(
                &response,
                Ok(Some(response)) if response.stop_reason == acp::StopReason::Cancelled
                    || response.stop_reason == acp::StopReason::Refusal
            );
            let result = match response {
                Ok(Some(response)) => match response.stop_reason {
                    acp::StopReason::Cancelled => Err(anyhow!("User canceled")),
                    acp::StopReason::MaxTokens => Err(anyhow!("The agent reached the maximum number of tokens.")),
                    acp::StopReason::MaxTurnRequests => Err(anyhow!("The agent reached the maximum number of allowed requests between user turns. Try prompting again.")),
                    acp::StopReason::Refusal => Err(anyhow!("The agent refused to process that prompt. Try again.")),
                    _ => thread.read_with(cx, |thread, _cx| {
                        thread
                            .last_message()
                            .and_then(|message| {
                                let content = message.as_agent_message()?
                                    .content
                                    .iter()
                                    .filter_map(|content| match content {
                                        AgentMessageContent::Text(text) => Some(text.as_str()),
                                        _ => None,
                                    })
                                    .join("\n\n");
                                if content.is_empty() {
                                    None
                                } else {
                                    Some(content)
                                }

View on GitHub (pinned to 916fc2b8cb)