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

Create/reconnect a session first and use the session ID returned by the agent

session not found

Error message

session not found

What it means

The x.ai/hooks/list extension handler builds a SessionId from the request and calls agent.list_hooks, which returns Option; None means no session with that ID is registered with the agent, and the handler converts that to the 'session not found' error. It is a lookup failure against the agent's live session registry, not a malformed request.

Source

Thrown at crates/codegen/xai-grok-shell/src/extensions/hooks.rs:218

        },
    };
    Some(ClientHookGroup {
        matcher,
        callback_ids: group.hook_callback_ids,
        timeout,
    })
}

pub async fn handle(agent: &MvpAgent, args: &acp::ExtRequest) -> ExtResult {
    match args.method.as_ref() {
        "x.ai/hooks/list" => {
            let req: ListRequest = super::parse_params(args)?;
            let sid = acp::SessionId::new(req.session_id);

            let result = agent
                .list_hooks(&sid)
                .await
                .ok_or_else(|| anyhow::anyhow!("session not found"));
            super::to_ext_response(result)
        }
        "x.ai/hooks/action" => {
            let req: xai_hooks_plugins_types::HooksActionRequest = super::parse_params(args)?;
            let sid = acp::SessionId::new(req.session_id);

            let result = agent
                .execute_hooks_action(&sid, req.action)
                .await
                .ok_or_else(|| anyhow::anyhow!("session not found"));
            super::to_ext_response(result)
        }
        _ => Err(acp::Error::method_not_found()),
    }
}

#[cfg(test)]
mod tests {

View on GitHub (pinned to bc7f02eddd)

Solutions

Create/reconnect a session first and use the session ID returned by the agent
Refresh the client's cached session ID instead of reusing one from before an agent restart
Handle the error by re-initializing the session and retrying the hooks/list call

Defensive patterns

Strategy: try-catch

Validate before calling

// track live sessions client-side; refuse to call with unknown IDs
if !live_sessions.contains(&req.session_id) {
    return Err("session is no longer live; re-create it".into());
}

Try / catch

match ext("x.ai/hooks/list", req).await {
    Ok(resp) => resp,
    Err(e) if e.to_string() == "session not found" => {
        let sid = create_session().await?;
        ext("x.ai/hooks/list", ListRequest { session_id: sid, ..req }).await
    }
    Err(e) => Err(e.into()),
}

Prevention

Invalidate cached session IDs on agent restart/disconnect
Listen for session-closed notifications and drop stale IDs
Create a session before any hooks call in a fresh process

When it happens

Trigger: Calling x.ai/hooks/list with a session_id that was never created or has already ended/closed in the agent process.

Common situations: Client retries with a cached session ID after agent restart; session timed out or was closed; typo'd/stale session ID passed by an IDE plugin.

Related errors

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