{"record":{"id":"15d997647b100ef7","repo":"chenglou/pretext","slug":"firefox-bidi-returned-no-browsing-context","errorCode":null,"errorMessage":"Firefox BiDi returned no browsing context","messagePattern":"Firefox BiDi returned no browsing context","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"scripts/browser-automation.ts","lineNumber":392,"sourceCode":"\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,\n    }\n  } catch (error) {\n    bidi?.close()\n    try {\n      firefoxProcess.kill('SIGTERM')\n    } catch {\n      // Best effort cleanup.\n    }\n    rmSync(profileDir, { recursive: true, force: true })\n    throw error\n  }","sourceCodeStart":374,"sourceCodeEnd":410,"githubUrl":"https://github.com/chenglou/pretext/blob/ac49b09b7d83ede19581fa94a8b892b07d309baf/scripts/browser-automation.ts#L374-L410","documentation":"Thrown during Firefox session initialization when browsingContext.getTree succeeded (no error field) but the returned contexts array is empty (contexts[0]?.context is undefined). Firefox launched with about:blank but reported zero usable browsing contexts, so there is nowhere to navigate. This is distinct from error 17 (which fires when getTree itself errors); here the call succeeded with empty content.","triggerScenarios":"Firefox opened in --headless with --new-instance but produced no browsing context — e.g. a content process failed to start, a sandbox policy blocked tab creation, or a profile lock prevented a real session. The BiDi handshake worked but the browser has no tab.","commonSituations":"Headless Firefox on a restricted/sandboxed environment where content processes cannot spawn; a profile that Firefox considers locked by another instance; a minimal/containerized environment lacking the resources to create a tab; Firefox startup race where the context appears slightly after the query.","solutions":["Re-run — if it is a startup race, a second attempt may catch the context after it appears.","Run Firefox headless manually with the same flags and confirm a tab opens (check about:debugging or ps for content processes).","Ensure no other Firefox instance is using the same profile dir (the script uses a fresh mkdtemp profile, but verify).","On containers/sandboxes, allow content-process forking and sufficient shared memory."],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":"function hasBrowsingContext(tree: { result?: { contexts?: Array<{ context: string }> } }): boolean {\n  return (tree.result?.contexts?.length ?? 0) > 0\n}","tryCatchPattern":"// Retry getTree once after a short delay in case the context appears late.\nlet contexts = (tree.result as { contexts: Array<{ context: string }> }).contexts\nif (contexts.length === 0) {\n  await sleep(500)\n  const retry = await bidi.send('browsingContext.getTree', {})\n  contexts = (retry.result as { contexts: Array<{ context: string }> }).contexts\n}\nif (contexts[0]?.context === undefined) throw new Error('Firefox BiDi returned no browsing context')","preventionTips":["Ensure headless Firefox can spawn content processes (check sandbox/container limits).","Use a fresh profile each run to avoid profile-lock contention.","Confirm memory and /dev/shm are sufficient in containers for a content process.","Re-run once — startup races sometimes resolve on the second attempt."],"tags":["browser-automation","firefox","webdriver-bidi","headless","browsing-context"],"backgroundTag":null,"analyzedSha":"ac49b09b7d83ede19581fa94a8b892b07d309baf","analyzedAt":"2026-08-12T17:03:16.263Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}