grafana/k6 · error

launching browser: %w

Error message

launching browser: %w

What it means

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.

Source

Thrown at internal/js/modules/k6/browser/chromium/browser_type.go:292

	flags, err := prepareFlags(opts, &(b.vu.State()).Options)
	if err != nil {
		return nil, 0, fmt.Errorf("%w", err)
	}

	dataDir := &storage.Dir{}
	if err := dataDir.Make(b.tmpdir(), flags["user-data-dir"]); err != nil {
		return nil, 0, fmt.Errorf("%w", err)
	}
	flags["user-data-dir"] = dataDir.Dir

	path, err := executablePath(opts.ExecutablePath, b.envLookupper, exec.LookPath)
	if err != nil {
		return nil, 0, fmt.Errorf("finding browser executable: %w", err)
	}

	browserProc, err := b.allocate(ctx, path, flags, dataDir, logger)
	if browserProc == nil {
		return nil, 0, fmt.Errorf("launching browser: %w", err)
	}

	// If this context is cancelled we'll initiate an extension wide
	// cancellation and shutdown.
	browserCtx, browserCtxCancel := context.WithCancel(vuCtx)
	b.Ctx = browserCtx
	browser, err := common.NewBrowser(ctx, browserCtx, browserCtxCancel,
		browserProc, opts, logger)
	if err != nil {
		return nil, 0, fmt.Errorf("launching browser: %w", err)
	}

	return browser, browserProc.Pid(), nil
}

// tmpdir returns the temporary directory to use for the browser.
// It returns the value of the TMPDIR environment variable if set,
// otherwise it returns an empty string.

View on GitHub (pinned to 93accf6570)

Solutions

  1. Run the resolved binary manually with the same flags to see the real error: /usr/bin/chromium --headless --no-sandbox --dump-dom about:blank
  2. 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)
  3. Verify TMPDIR is writable and has space, or point it elsewhere (export TMPDIR=/tmp/k6)
  4. Remove or fix custom options.args entries one by one to find the flag Chrome chokes on
  5. Raise K6_BROWSER_TIMEOUT if startup on cold caches exceeds the default

Example fix

# before
FROM debian:slim
RUN apt-get install -y k6 chromium  # missing runtime libs -> exec fails

# after
RUN apt-get update && apt-get install -y chromium libnss3 libgbm1 libatk-bridge2.0-0
ENV K6_BROWSER_EXECUTABLE_PATH=/usr/bin/chromium
Defensive patterns

Strategy: try-catch

Try / catch

try {
  const browser = chromium.launch({ args: ['--no-sandbox'] });
} catch (e) {
  const m = String(e.message);
  if (m.includes('launching browser')) {
    // exec-level failure: run the binary manually with the same flags to see the OS error
    console.error('Chrome failed to start. Check missing libs, TMPDIR, and args:', m);
  }
  throw e;
}

Prevention

When it happens

Trigger: 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).

Common situations: 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.

Related errors

AI-assisted analysis of grafana/k6@93accf6570 (2026-08-15). Data as JSON: /api/errors/d164aa219746c29e. Report an issue: GitHub.