Hmbown/CodeWhale · error

Cannot resume agent : sub-agent depth limit reached…

Error message

Cannot resume agent {agent_id}: sub-agent depth limit reached (current {}, max {})

What it means

When resuming a sub-agent, its saved spawn identity (parent, depth, max depth) is restored onto the runtime. If the restored depth exceeds the (clamped) maximum spawn depth, resume is refused to prevent an interrupted child from re-entering the tree deeper than the configured limit.

Solutions

1. Raise `[subagents] max_spawn_depth` in the Workflow config to at least the child's saved depth shown in the error.
2. Instead of resuming, spawn the remaining work as a shallower sibling agent.
3. Let the parent agent handle the work directly rather than re-nesting.

Example fix

// before
[subagents]
max_spawn_depth = 2

// after
[subagents]
max_spawn_depth = 4  # >= saved child depth reported by resume error

// pre-flight before resume
let depth_ok = saved_depth <= max_spawn_depth_from_config();
if !depth_ok { raise_max_spawn_depth(saved_depth); }

match agents.resume(agent_id) {
    Err(e) if e.to_string().contains("depth limit reached") => {
        // respawn at shallower depth or bump [subagents] max_spawn_depth
        spawn_shallow_fallback(task)
    }
    other => other?,
}

When it happens

Trigger: Calling resume on an agent whose saved `spawn_depth` is greater than `min(runtime.max_spawn_depth, saved max_depth)`. Typically after the operator lowered `[subagents] max_spawn_depth` between the original spawn and the resume, or when resuming a deeply nested child near the absolute cap.

Common situations: Config tightening after an interruption; a child spawned at depth N whose parent chain now enforces a smaller max; replaying a saved session recorded under a larger depth budget.

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

• Cannot resume agent on its saved provider
• Sub-agent depth limit reached
• Agent has no continuable checkpoint to resume from…
• Sub-agent admission limit reached
• Sub-agent depth limit reached

AI-assisted analysis of Hmbown/CodeWhale@73e0f67d83 (2026-09-22). Data as JSON: /api/errors/5c616a862612cc8f. Report an issue: GitHub.

Appendix: source

Thrown at crates/tui/src/tools/subagent/mod.rs:6291

                build_resume_prompt(&agent.prompt, checkpoint, followup_text),
                agent.assignment.clone(),
                agent.allowed_tools.clone(),
                agent.model.clone(),
                agent.fork_context,
                agent.workspace.clone(),
                claim,
                preserved_profile,
                child_route,
            )
        };
        let mut runtime = runtime.background_runtime();
        if let Some((parent, depth, max_depth)) = saved_identity {
            runtime.parent_agent_id = parent;
            runtime.spawn_depth = depth;
            runtime.max_spawn_depth = runtime.max_spawn_depth.min(max_depth);
        }
        if runtime.spawn_depth > runtime.max_spawn_depth {
            return Err(anyhow!(
                "Cannot resume agent {agent_id}: sub-agent depth limit reached (current {}, max {})",
                runtime.spawn_depth,
                runtime.max_spawn_depth
            ));
        }
        runtime.context.workspace = workspace;
        // Rebind the child's saved provider pin (#6046). The resumed runtime
        // is derived from the caller, whose active provider can differ from
        // the provider the child was spawned under; without this rebind the
        // saved model is validated against the caller's provider and rejected
        // as a foreign model for a direct provider. `bind_spawn_provider` is
        // a no-op when the pin already matches, so same-provider children are
        // unaffected. Borrow the receipt: it is moved into the spawn options
        // below.
        if let Some(saved_route) = child_route.as_ref() {
            bind_spawn_provider(&mut runtime, &saved_route.provider_id).map_err(|error| {
                anyhow!(
                    "Cannot resume agent {agent_id} on its saved provider '{}': {error}",

View on GitHub (pinned to 73e0f67d83)