xai-org/grok-build · error

-32602

-32602

Error message

Cannot switch to model '{}': it requires agent '{}' but the active agent is '{}'. Start a new session to use this model.

What it means

This is an ACP (agent client protocol) error surfaced as JSON-RPC -32602 (InvalidRequest). The user attempted to switch the session's model, but the requested model is bound to a different agent type than the one currently active in the session. Since an agent type cannot be changed mid-session, the caller must start a new session; the error carries structured `data` (model_id, required_agent_type, active_agent_type) that clients can parse via `from_acp_error`.

Source

Thrown at crates/codegen/xai-grok-shell/src/agent/config.rs:5527

    pub code: String,
    /// The agent type currently active in the session.
    pub active_agent_type: String,
    /// The agent type required by the target model.
    pub required_agent_type: String,
    /// The model ID that was requested.
    pub model_id: String,
    /// Remediation hint for the client.
    pub suggestion: String,
}
impl ModelSwitchIncompatibleAgentError {
    /// Build an `acp::Error` with this structured payload.
    pub(crate) fn into_acp_error(self) -> acp::Error {
        let message = format!(
            "Cannot switch to model '{}': it requires agent '{}' but the active agent is '{}'. \
             Start a new session to use this model.",
            self.model_id, self.required_agent_type, self.active_agent_type,
        );
        acp::Error::new(acp::ErrorCode::InvalidRequest.into(), message)
            .data(serde_json::to_value(&self).ok())
    }
    /// Try to parse from an `acp::Error.data` field.
    pub fn from_acp_error(err: &acp::Error) -> Option<Self> {
        let data = err.data.as_ref()?;
        let code = data.get("code")?.as_str()?;
        if code != MODEL_SWITCH_INCOMPATIBLE_AGENT {
            return None;
        }
        serde_json::from_value(data.clone()).ok()
    }
    /// Render a user-friendly error message for the TUI.
    pub fn user_message(&self) -> String {
        format!(
            "Cannot switch to '{}' — it requires agent '{}' but the active agent is '{}'. \
             Start /new to use this model.",
            self.model_id, self.required_agent_type, self.active_agent_type,
        )

View on GitHub (pinned to bc7f02eddd)

Solutions

1. Start a new session with the required agent type, then select the model
2. Choose a different model that is compatible with the currently active agent type
3. Parse `err.data` with `from_acp_error` to show the user which agent the model requires and which is active
4. Fix client-side model pickers to filter models by the active agent type

Example fix

// before
client.set_model(session_id, "grok-plan-only-model") // requires agent 'planner', active 'coder'
// after
let new_session = client.new_session_with_agent("planner")?;
client.set_model(new_session.id, "grok-plan-only-model")?

// before switching, check the model's agent compatibility via from_acp_error data on failure,
// or track model -> required_agent mapping client-side and filter the picker:
let compatible = models.iter().filter(|m| m.required_agent == active_agent);

fn is_agent_mismatch(err: &acp::Error) -> bool {
    err.code == acp::ErrorCode::InvalidRequest.into()
        && err.message.contains("requires agent")
        && ModelSwitchError::from_acp_error(err).is_some()
}

match client.set_model(session_id, &model_id).await {
    Err(err) if is_agent_mismatch(&err) => {
        let info = ModelSwitchError::from_acp_error(&err).unwrap();
        prompt_new_session(&info.required_agent_type);
    }
    other => other,
}

When it happens

Trigger: Calling the model-switch / `session/set_model` style request with a `model_id` whose required agent type differs from the session's active agent type.

Common situations: Picking a model from a global model list without noticing it belongs to another agent (e.g. a plan/agent-specific model); a client UI persisting a previously selected model that was tied to another agent; resuming a session and switching models across agent kinds.

Related errors

• ACP response missing result field
• -32601
• -32602
• -32601
• -32601

AI-assisted analysis of xai-org/grok-build@bc7f02eddd (2026-08-31). Data as JSON: /api/errors/9e45662cfeb2b537. Report an issue: GitHub.