What causes "session not found" in xai-org/grok-build?

Use a session ID owned by the agent instance receiving the request (sticky routing in multi-instance setups)

session not found

Error message

session not found

What it means

The x.ai/plugins/action handler calls agent.execute_plugins_action with a SessionId; an Option::None result (session not registered with this agent) is mapped to the 'session not found' error. It indicates the agent has no live session matching the supplied ID when performing a plugin action.

Source

Thrown at crates/codegen/xai-grok-shell/src/extensions/plugins.rs:168

                        .iter()
                        .map(|p| loaded_plugin_to_info(p))
                        .collect();
                    PluginsListResponse { plugins }
                }
                None => PluginsListResponse {
                    plugins: Vec::new(),
                },
            };
            super::to_ext_response(Ok::<_, anyhow::Error>(response))
        }
        "x.ai/plugins/action" => {
            let req: xai_hooks_plugins_types::PluginsActionRequest = super::parse_params(args)?;
            let sid = acp::SessionId::new(req.session_id);

            let result = agent
                .execute_plugins_action(&sid, req.action)
                .await
                .ok_or_else(|| anyhow::anyhow!("session not found"));
            super::to_ext_response(result)
        }
        "x.ai/plugins/notify-updates" => {
            // Broadcast a PluginUpdatesInstalled notification to the session.
            #[derive(serde::Deserialize)]
            #[serde(rename_all = "camelCase")]
            struct NotifyUpdatesRequest {
                session_id: String,
                updates: Vec<(String, String, String)>, // (name, old_ver, new_ver)
            }
            let req: NotifyUpdatesRequest = super::parse_params(args)?;
            let sid = acp::SessionId::new(req.session_id);
            if let Some(handle) = agent.get_session_handle(&sid) {
                handle.notify_plugin_updates(req.updates).await;
            }
            super::to_ext_response(Ok::<_, anyhow::Error>(serde_json::json!({ "ok": true })))
        }
        _ => Err(acp::Error::method_not_found()),

View on GitHub (pinned to bc7f02eddd)

Solutions

Use a session ID owned by the agent instance receiving the request (sticky routing in multi-instance setups)
Re-establish the session and retry the plugin action
Invalidate cached session IDs on disconnect/restart events in the client

Defensive patterns

Strategy: retry

Validate before calling

// ensure the target agent owns the session before dispatch
if agent_owner_of(&req.session_id) != current_agent_instance {
    return Err("session belongs to a different agent instance".into());
}

Try / catch

// retry once after re-establishing the session
match ext("x.ai/plugins/action", req.clone()).await {
    Err(e) if e.to_string() == "session not found" => {
        req.session_id = create_session().await?;
        ext("x.ai/plugins/action", req).await
    }
    r => r,
}

Prevention

Use sticky routing so session requests reach the owning agent instance
Refresh session IDs after reconnects or failovers
Log agent instance ID with each session to detect cross-instance calls

When it happens

Trigger: Calling x.ai/plugins/action with a session_id that doesn't exist, has closed, or belongs to a different agent instance (e.g. after restart or when multiple agent processes are running).

Common situations: Load-balanced/multi-process setups where the action hits an agent that doesn't own the session; stale IDs cached by tooling; session expiry.

Related errors

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