{"record":{"id":"d164aa219746c29e","repo":"grafana/k6","slug":"launching-browser-w","errorCode":null,"errorMessage":"launching browser: %w","messagePattern":"launching browser: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/js/modules/k6/browser/chromium/browser_type.go","lineNumber":292,"sourceCode":"\tflags, err := prepareFlags(opts, &(b.vu.State()).Options)\n\tif err != nil {\n\t\treturn nil, 0, fmt.Errorf(\"%w\", err)\n\t}\n\n\tdataDir := &storage.Dir{}\n\tif err := dataDir.Make(b.tmpdir(), flags[\"user-data-dir\"]); err != nil {\n\t\treturn nil, 0, fmt.Errorf(\"%w\", err)\n\t}\n\tflags[\"user-data-dir\"] = dataDir.Dir\n\n\tpath, err := executablePath(opts.ExecutablePath, b.envLookupper, exec.LookPath)\n\tif err != nil {\n\t\treturn nil, 0, fmt.Errorf(\"finding browser executable: %w\", err)\n\t}\n\n\tbrowserProc, err := b.allocate(ctx, path, flags, dataDir, logger)\n\tif browserProc == nil {\n\t\treturn nil, 0, fmt.Errorf(\"launching browser: %w\", err)\n\t}\n\n\t// If this context is cancelled we'll initiate an extension wide\n\t// cancellation and shutdown.\n\tbrowserCtx, browserCtxCancel := context.WithCancel(vuCtx)\n\tb.Ctx = browserCtx\n\tbrowser, err := common.NewBrowser(ctx, browserCtx, browserCtxCancel,\n\t\tbrowserProc, opts, logger)\n\tif err != nil {\n\t\treturn nil, 0, fmt.Errorf(\"launching browser: %w\", err)\n\t}\n\n\treturn browser, browserProc.Pid(), nil\n}\n\n// tmpdir returns the temporary directory to use for the browser.\n// It returns the value of the TMPDIR environment variable if set,\n// otherwise it returns an empty string.","sourceCodeStart":274,"sourceCodeEnd":310,"githubUrl":"https://github.com/grafana/k6/blob/93accf6570dcd306ca5e99cc44c393ee3797761b/internal/js/modules/k6/browser/chromium/browser_type.go#L274-L310","documentation":"Returned by BrowserType.launch when b.allocate() returns a nil process, meaning the local Chrome process could not be started. allocate() first parses flags (parseArgs can fail on an invalid flag value type) and then common.NewLocalBrowserProcess execs the binary; failure there (exec error, process died immediately, could not prepare the user-data dir) bubbles up wrapped as 'launching browser'. Connect wraps it further in UserFriendlyError with timeout hints.","triggerScenarios":"chromium.launch() where the resolved binary fails to exec (missing shared libraries, e.g. missing libnss3 on a slim image); parseArgs rejecting a non-string/non-bool flag value; the spawned Chrome exits immediately due to an invalid combination of args; the temporary user-data-dir cannot be created (TMPDIR unwritable, disk full).","commonSituations":"Debian/alpine containers missing Chrome runtime deps (libnss3, libatk, libgbm); TMPDIR pointing to a read-only volume; passing custom args via options.args that Chrome rejects and exits on; sandbox errors in containers requiring --no-sandbox (already implied in some images but not all); SELinux blocking execve.","solutions":["Run the resolved binary manually with the same flags to see the real error: /usr/bin/chromium --headless --no-sandbox --dump-dom about:blank","Install missing Chrome runtime libraries (apt-get install -y libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1 libpango-1.0-0 libcairo2)","Verify TMPDIR is writable and has space, or point it elsewhere (export TMPDIR=/tmp/k6)","Remove or fix custom options.args entries one by one to find the flag Chrome chokes on","Raise K6_BROWSER_TIMEOUT if startup on cold caches exceeds the default"],"exampleFix":"# before\nFROM debian:slim\nRUN apt-get install -y k6 chromium  # missing runtime libs -> exec fails\n\n# after\nRUN apt-get update && apt-get install -y chromium libnss3 libgbm1 libatk-bridge2.0-0\nENV K6_BROWSER_EXECUTABLE_PATH=/usr/bin/chromium","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  const browser = chromium.launch({ args: ['--no-sandbox'] });\n} catch (e) {\n  const m = String(e.message);\n  if (m.includes('launching browser')) {\n    // exec-level failure: run the binary manually with the same flags to see the OS error\n    console.error('Chrome failed to start. Check missing libs, TMPDIR, and args:', m);\n  }\n  throw e;\n}","preventionTips":["Smoke-test the Chrome binary in the same container before running k6","Keep TMPDIR writable and spacious; disk-full is a classic silent cause","Add container flags like --no-sandbox/--disable-gpu when the runtime needs them","Change only one custom arg at a time so a rejected flag is easy to spot"],"tags":["launch","process","docker","dependencies","environment"],"backgroundTag":null,"analyzedSha":"93accf6570dcd306ca5e99cc44c393ee3797761b","analyzedAt":"2026-08-15T21:23:27.118Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}