{"record":{"id":"c43b1f3e2acac76b","repo":"microsoft/playwright","slug":"cannot-launch-firefox-with-relative-home-directory","errorCode":null,"errorMessage":"Cannot launch Firefox with relative home directory. Did you set ${os.platform() === 'win32' ? 'USERPROFILE' : 'HOME'} to a relative path?","messagePattern":"Cannot launch Firefox with relative home directory\\. Did you set (.+?) to a relative path\\?","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/playwright-core/src/server/bidi/bidiFirefox.ts","lineNumber":57,"sourceCode":"  override executablePath(): string {\n    return '';\n  }\n\n  override async connectToTransport(transport: ConnectionTransport, options: BrowserOptions): Promise<BidiBrowser> {\n    return BidiBrowser.connect(this.attribution.playwright, transport, options);\n  }\n\n  override doRewriteStartupLog(logs: string): string {\n    if (logs.includes(`as root in a regular user's session is not supported.`))\n      logs = '\\n' + wrapInASCIIBox(`Firefox is unable to launch if the $HOME folder isn't owned by the current user.\\nWorkaround: Set the HOME=/root environment variable${process.env.GITHUB_ACTION ? ' in your GitHub Actions workflow file' : ''} when running Playwright.`, 1);\n    if (logs.includes('no DISPLAY environment variable specified'))\n      logs = '\\n' + wrapInASCIIBox(kNoXServerRunningError, 1);\n    return logs;\n  }\n\n  override amendEnvironment(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {\n    if (!path.isAbsolute(os.homedir()))\n      throw new Error(`Cannot launch Firefox with relative home directory. Did you set ${os.platform() === 'win32' ? 'USERPROFILE' : 'HOME'} to a relative path?`);\n\n    env = {\n      ...env,\n      'MOZ_CRASHREPORTER': '1',\n      'MOZ_CRASHREPORTER_NO_REPORT': '1',\n      'MOZ_CRASHREPORTER_SHUTDOWN': '1',\n    };\n\n    if (os.platform() === 'linux') {\n      // Always remove SNAP_NAME and SNAP_INSTANCE_NAME env variables since they\n      // confuse Firefox: in our case, builds never come from SNAP.\n      // See https://github.com/microsoft/playwright/issues/20555\n      return { ...env, SNAP_NAME: undefined, SNAP_INSTANCE_NAME: undefined };\n    }\n    return env;\n  }\n\n  override attemptToGracefullyCloseBrowser(transport: ConnectionTransport) {","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/microsoft/playwright/blob/c8fc3bf8d31542d59b4d4d9eaab1df93ff541dc6/packages/playwright-core/src/server/bidi/bidiFirefox.ts#L39-L75","documentation":"Before launching Firefox, Playwright checks `os.homedir()` is absolute because Firefox (via its launcher/crashreporter) misbehaves or crashes with a relative HOME. The message names the correct env var per platform (USERPROFILE on Windows, HOME elsewhere).","triggerScenarios":"`firefox.launch()` or any Firefox launch (incl. BiDi) when HOME (Linux/macOS) or USERPROFILE (Windows) resolves to a relative path via `os.homedir()`.","commonSituations":"Misconfigured Docker/CI images where HOME is unset or relative; shell rc files exporting a relative HOME; systemd units with `HOME=.`; WSL/Windows env mixups; containers running as a UID with no passwd entry.","solutions":["Set HOME to an absolute path: `export HOME=/root` (Linux) or fix USERPROFILE (Windows)","In GitHub Actions add `env: { HOME: '/root' }` to the step","In Dockerfiles use `ENV HOME=/root`","Verify before launch: `node -e \"console.log(require('os').homedir())\"`"],"exampleFix":"// before (env: HOME=relative/path)\nconst b = await firefox.launch();\n\n// after\n// shell: export HOME=/root\n// or in CI yaml: env: HOME: /root\nconst b = await firefox.launch();","handlingStrategy":"validation","validationCode":"import path from 'path';\nimport os from 'os';\n\nfunction ensureAbsoluteHome(): void {\n  const home = os.homedir();\n  if (!path.isAbsolute(home)) {\n    throw new Error(\n      `HOME must be absolute (got '${home}'). Run: export HOME=$HOME on POSIX or fix USERPROFILE on Windows.`\n    );\n  }\n}\nensureAbsoluteHome();\nawait firefox.launch();","typeGuard":null,"tryCatchPattern":null,"preventionTips":["In Docker/CI set `ENV HOME=/root` or `export HOME=$HOME`","Verify with `node -e \"console.log(require('os').homedir())\"` in your environment","Run Firefox launch under the same UID that owns $HOME"],"tags":["firefox","launch","environment","ci","docker"],"backgroundTag":null,"analyzedSha":"c8fc3bf8d31542d59b4d4d9eaab1df93ff541dc6","analyzedAt":"2026-08-12T07:26:36.950Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}