What causes "Session "${sessionId}" not found." in vitest-dev/vitest?

Ensure the browser test (and its orchestrator page) is still connected when issuing the CDP call.

vitest-dev/vitest · error · Error

Session "${sessionId}" not found.

Error message

Session "${sessionId}" not found.

What it means

`ensureCDPHandler` looks up `sessionId` in `vitest._browserSessions`. The session is created when a browser test run begins and destroyed when the orchestrator websocket closes. If the id doesn't match a live session, the CDP handler cannot be created.

Source

Thrown at packages/browser/src/node/projectParent.ts:199

    options: StackTraceParserOptions = {},
  ): ParsedStack[] {
    return parseStacktrace(trace, {
      ...this.stackTraceOptions,
      ...options,
    })
  }

  public readonly cdps: Map<string, BrowserServerCDPHandler> = new Map()
  private cdpSessionsPromises = new Map<string, Promise<CDPSession>>()

  async ensureCDPHandler(sessionId: string, rpcId: string): Promise<BrowserServerCDPHandler> {
    const cachedHandler = this.cdps.get(rpcId)
    if (cachedHandler) {
      return cachedHandler
    }
    const browserSession = this.vitest._browserSessions.getSession(sessionId)
    if (!browserSession) {
      throw new Error(`Session "${sessionId}" not found.`)
    }

    const browser = browserSession.project.browser!
    const provider = browser.provider
    if (!provider) {
      throw new Error(`Browser provider is not defined for the project "${browserSession.project.name}".`)
    }
    if (!provider.getCDPSession) {
      throw new Error(`CDP is not supported by the provider "${provider.name}".`)
    }

    const session = await this.cdpSessionsPromises.get(rpcId) ?? await (async () => {
      const promise = provider.getCDPSession!(sessionId).finally(() => {
        this.cdpSessionsPromises.delete(rpcId)
      })
      this.cdpSessionsPromises.set(rpcId, promise)
      return promise
    })()

View on GitHub (pinned to d568f8ce37)

Solutions

Ensure the browser test (and its orchestrator page) is still connected when issuing the CDP call.
Re-fetch the current sessionId rather than caching it across runs.
If this happens mid-run, the session may have been torn down by an earlier error — check the test log for connection-close messages.

Example fix

// before
const cdp = await ensureCDPHandler(staleSessionId, rpcId)

// after
const sessionId = vitest._browserSessions.currentSessionId
const cdp = await ensureCDPHandler(sessionId, rpcId)

Defensive patterns

Strategy: validation

Validate before calling

function sessionActive(vitest: { _browserSessions: { sessionIds: Set<string> } }, id: string): boolean {
  return vitest._browserSessions.sessionIds.has(id)
}

Try / catch

try {
  await cdp.send('Page.reload')
} catch (err) {
  if (err instanceof Error && /Session ".*" not found/.test(err.message)) {
    // re-establish the browser session
  }
  throw err
}

Prevention

Don't cache sessionId across runs — fetch the live one each time.
Ensure the browser/orchestrator page stays open for the duration of CDP usage.
Check for connection-close messages in the test log if sessions vanish mid-run.

When it happens

Trigger: Calling `cdp.send(...)` (or any API that routes through `ensureCDPHandler`) with a sessionId that was never created, was already destroyed (page/orchestrator closed), or was passed in wrong.

Common situations: Calling CDP after the browser tab was closed; race where CDP is requested before the session is registered; passing a stale sessionId cached across test runs.

Related errors

AI-assisted analysis of vitest-dev/vitest@d568f8ce37 (2026-08-03). Data as JSON: /data/errors/36619e40dd8f91fd.json. Report an issue: GitHub.