grafana/k6 · error

finding browser executable: %w

Error message

finding browser executable: %w

What it means

Returned by BrowserType.launch when executablePath() cannot resolve a Chrome/Chromium binary. It wraps either ErrChromeNotFoundAtPath (an explicit executablePath was given but exec.LookPath failed) or ErrChromeNotInstalled (none of the well-known names — headless_shell, chromium, google-chrome, chrome.exe, the macOS app paths, USERPROFILE fallback — resolved). Launch aborts before any process is spawned.

Source

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

}

func (b *BrowserType) launch(
	ctx, vuCtx context.Context, opts *common.BrowserOptions, logger *log.Logger,
) (_ *common.Browser, pid int, _ error) {
	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

View on GitHub (pinned to 93accf6570)

Solutions

1. Install Chrome or Chromium (e.g. apt-get install -y chromium or the google-chrome-stable package), or use the k6 browser docker image which ships headless_shell
2. Set an explicit executable path: options.executablePath = '/usr/bin/chromium' (or export K6_BROWSER_EXECUTABLE_PATH=/usr/bin/google-chrome) and verify it exists with ls
3. Ensure the file is executable (chmod +x) and the path is absolute when launched from another working directory
4. If using headless_shell from the k6 image, confirm it is on PATH (it is by default in grafana/k6 images with browser support)

Example fix

# before (no chrome in container)
k6 run browser_test.js

# after
## Dockerfile
FROM grafana/k6:0.5x-with-browser
# headless_shell is already included and on PATH

## or in the script
const browser = chromium.launch({ executablePath: '/usr/bin/google-chrome-stable' });

try {
  const browser = chromium.launch({ executablePath: __ENV.CHROME_PATH });
} catch (e) {
  const m = String(e.message);
  if (m.includes('finding browser executable')) {
    console.error('No Chrome/Chromium found. Install one or set K6_BROWSER_EXECUTABLE_PATH.', m);
  }
  throw e;
}

When it happens

Trigger: chromium.launch() on a host with no Chrome/Chromium installed; executablePath option pointing to a wrong/nonexistent/relative path or a file without execute permission; minimal Docker images (alpine/distroless/slim) with no browser package; PATH not including the Chrome directory.

Common situations: Running k6 in a slim CI container without installing Chromium; pointing K6_BROWSER_EXECUTABLE_PATH at a path inside a different container; SELinux/AppArmor denying execution; the binary exists but is not on PATH and no explicit path was set.

Related errors

• k6 couldn't detect google chrome or a chromium-supported bro
• launching browser: %w
• both K6_CLOUD_METRICS_PUSH_URL and K6_CLOUD_TEST_RUN_TOKEN m
• K6_CLOUD_LOGS_PUSH_URL requires K6_CLOUD_TEST_RUN_TOKEN
• WebSocket endpoint cannot be empty

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