What causes "Session does not exist." in apache/shardingsphere?

Re-run the MCP initialize handshake and use the newly returned session id.

apache/shardingsphere · error · MCPSessionNotExistedException

Session does not exist.

Error message

Session does not exist.

What it means

MCPSessionManager.getRequiredExecutionLock looks up the per-session state (which owns a ReentrantLock serializing executions); when no SessionState exists for the sessionId it throws MCPSessionNotExistedException ('Session does not exist.'). This fires when an execution is requested against a session id the manager no longer tracks — never initialized, already closed, or removed after server restart. It is the generic unknown-session guard for any code path requiring the session's execution lock.

Source

Thrown at mcp/core/src/main/java/org/apache/shardingsphere/mcp/core/session/MCPSessionManager.java:133

            if (sessionState == sessions.get(sessionId)) {
                try {
                    notifySessionCloseListeners(sessionId);
                } finally {
                    sessions.remove(sessionId, sessionState);
                }
            }
        }
    }
    
    ReentrantLock findExecutionLock(final String sessionId) {
        SessionState sessionState = sessions.get(sessionId);
        return null == sessionState ? null : sessionState.executionLock;
    }
    
    ReentrantLock getRequiredExecutionLock(final String sessionId) {
        ReentrantLock result = findExecutionLock(sessionId);
        if (null == result) {
            throw new MCPSessionNotExistedException();
        }
        return result;
    }
    
    Set<String> getSessionIds() {
        return new LinkedHashSet<>(sessions.keySet());
    }
    
    private SessionState getRequiredSessionState(final String sessionId) {
        SessionState result = sessions.get(sessionId);
        if (null == result) {
            throw new MCPSessionNotExistedException();
        }
        return result;
    }
    
    private void notifySessionCloseListeners(final String sessionId) {
        for (Consumer<String> each : sessionCloseListeners) {

View on GitHub (pinned to e952770a21)

Solutions

Re-run the MCP initialize handshake and use the newly returned session id.
Confirm the Mcp-Session-Id header is sent verbatim from the InitializeResult on every subsequent request.
If deployed with multiple nodes, ensure sticky routing or shared session state for HTTP transport.
Handle the session-not-existed error code in the client as a signal to transparently re-initialize.

Example fix

// before
const sessionId = loadFromDisk() ?? 'guess-1234'; // stale after server restart
await mcp.callTool(sessionId, 'database_gateway_execute_query', args); // Session does not exist.

// after
async function withSession(mcp, args) {
  try { return await mcp.callTool(getSessionId(), 'database_gateway_execute_query', args); }
  catch (e) { if (e.code === 'SESSION_NOT_EXISTED') { setSessionId(await mcp.initialize());
              return mcp.callTool(getSessionId(), 'database_gateway_execute_query', args); } throw e; }
}

Defensive patterns

Strategy: retry

Validate before calling

// Confirm the session is alive before issuing tool calls
const ids = await mcp.request('sessions/list'); // where exposed; else rely on initialize bookkeeping
if (!ids.includes(sessionId)) sessionId = (await mcp.request('initialize', initParams)).sessionId;

Try / catch

try {
  return await callToolWithSession(sessionId, tool, args);
} catch (e) {
  if (e.message === 'Session does not exist.' || e.code === 'SESSION_NOT_EXISTED') {
    sessionId = (await mcp.request('initialize', initParams)).sessionId; // re-handshake once
    return callToolWithSession(sessionId, tool, args);
  }
  throw e;
}

Prevention

Persist the session id immediately after initialize and never fabricate one.
Treat server restarts/deploys as implicit session invalidation; re-initialize on reconnect.
Implement single automatic re-initialize-and-retry on session-not-existed.
With multiple server nodes, use sticky routing so the session-bearing node receives requests.

When it happens

Trigger: Invoking a tool that runs under the session execution lock with a session id that is absent from the sessions map: an id from a previous server process, an id removed by closeSession/remove, or a fabricated/garbled Mcp-Session-Id header value.

Common situations: Server restart or redeploy while a long-lived client keeps using an old session id; session expired/closed due to inactivity timeout; load balancer routing requests to a node that never hosted the session; client losing the initialize response and guessing an id.

Related errors

AI-assisted analysis of apache/shardingsphere@e952770a21 (2026-08-14). Data as JSON: /api/errors/25530d5f85ccfd03. Report an issue: GitHub.