{"record":{"id":"c1483e5b3896e7e7","repo":"chenglou/pretext","slug":"session-message-session-error","errorCode":null,"errorMessage":"${session.message ?? session.error}","messagePattern":"\\$\\{session\\.message \\?\\? session\\.error\\}","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"scripts/browser-automation.ts","lineNumber":381,"sourceCode":"    '--profile',\n    profileDir,\n    '--remote-debugging-port',\n    String(bidiPort),\n    'about:blank',\n  ], {\n    cwd: process.cwd(),\n    stdio: 'ignore',\n  })\n\n  let bidi: FirefoxBidiClient | null = null\n\n  try {\n    await waitForPort(bidiPort)\n    bidi = await connectFirefoxBidi(bidiPort)\n\n    const session = await bidi.send('session.new', { capabilities: { alwaysMatch: {} } })\n    if (session.error !== undefined) {\n      throw new Error(session.message ?? session.error)\n    }\n\n    const tree = await bidi.send('browsingContext.getTree', {})\n    if (tree.error !== undefined) {\n      throw new Error(tree.message ?? tree.error)\n    }\n\n    const contexts = (tree.result as { contexts: Array<{ context: string }> }).contexts\n    const context = contexts[0]?.context\n    if (context === undefined) {\n      throw new Error('Firefox BiDi returned no browsing context')\n    }\n\n    return {\n      bidi,\n      context,\n      firefoxProcess,\n      profileDir,","sourceCodeStart":363,"sourceCodeEnd":399,"githubUrl":"https://github.com/chenglou/pretext/blob/ac49b09b7d83ede19581fa94a8b892b07d309baf/scripts/browser-automation.ts#L363-L399","documentation":"Thrown during Firefox session initialization when the WebDriver BiDi 'session.new' command returns an error object. The BiDi client surfaces protocol-level errors as { error, message }; this throw picks message when present, else the error code. It means Firefox accepted the TCP connection (waitForPort passed) but its BiDi endpoint rejected session creation — typically a capability or version problem.","triggerScenarios":"Firefox BiDi session.new returns { error: '...', message: '...' } — capability alwaysMatch:{} unsupported by the installed Firefox version; Firefox too old to support BiDi; the remote-debugging-port is a legacy Marionette endpoint rather than BiDi; profile incompatibility.","commonSituations":"Firefox version predates WebDriver BiDi support (need a recent version); a Firefox update changed BiDi capability negotiation; a corrupted profile passed via --profile; conflicting Marionette/RemoteProtocol flags.","solutions":["Upgrade Firefox to a recent release with full WebDriver BiDi support.","Launch Firefox manually with the same flags (--headless --new-instance --remote-debugging-port <port>) and check about:debugging / the console for capability errors.","Clear the profile dir and let the script create a fresh one.","Read the exact message field — it usually names the unsupported capability or version mismatch."],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"// Verify Firefox supports WebDriver BiDi before launching.\n// (No runtime API; check the installed version against Mozilla's BiDi minimum.)\nimport { execFileSync } from 'node:child_process'\nconst ver = execFileSync('/Applications/Firefox.app/Contents/MacOS/firefox', ['--version'], { encoding: 'utf8' })\nif (Number.parseInt(ver.match(/(\\d+)\\./)?.[1] ?? '0', 10) < 113) {\n  throw new Error('Firefox >= 113 required for WebDriver BiDi')\n}","typeGuard":"function isBidiError(reply: { error?: unknown, message?: unknown }): boolean {\n  return reply.error !== undefined\n}","tryCatchPattern":"// initializeFirefoxSession already cleans up Firefox on this error; the caller should retry once.\ntry {\n  session = await initializeFirefoxSession()\n} catch (error) {\n  // one retry for transient capability negotiation failures\n  session = await initializeFirefoxSession()\n}","preventionTips":["Keep Firefox updated to a recent release with stable WebDriver BiDi.","Let the script create a fresh profile each run; do not reuse a locked profile.","Read the BiDi message field to pinpoint the capability or version mismatch.","Launch Firefox manually with the same flags to reproduce capability errors."],"tags":["browser-automation","firefox","webdriver-bidi","session","capability"],"backgroundTag":null,"analyzedSha":"ac49b09b7d83ede19581fa94a8b892b07d309baf","analyzedAt":"2026-08-12T17:03:16.263Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}