grafana/k6 · error · ErrChromeNotInstalled

k6 couldn't detect google chrome or a chromium-supported bro

Error message

k6 couldn't detect google chrome or a chromium-supported browser on this system

What it means

When neither an explicit executable path nor a WS endpoint is configured, k6 searches the OS's default locations for a Chrome/Chromium binary. ErrChromeNotInstalled means that search found nothing usable, so k6 has no local browser to launch for the browser scenario.

Source

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

) (_ *common.BrowserProcess, rerr error) {
	bProcCtx, bProcCtxCancel := context.WithCancelCause(ctx)
	defer func() {
		if rerr != nil {
			bProcCtxCancel(errors.New("local browser process init failed"))
		}
	}()

	args, err := parseArgs(flags)
	if err != nil {
		return nil, err
	}

	return common.NewLocalBrowserProcess(bProcCtx, path, args, dataDir, bProcCtxCancel, logger) //nolint: wrapcheck
}

var (
	// ErrChromeNotInstalled is returned when the Chrome executable is not found.
	ErrChromeNotInstalled = errors.New(
		"k6 couldn't detect google chrome or a chromium-supported browser on this system",
	)

	// ErrChromeNotFoundAtPath is returned when the Chrome executable is not found at the given path.
	ErrChromeNotFoundAtPath = errors.New(
		"k6 couldn't detect google chrome or a chromium-supported browser on the given path",
	)
)

// executablePath returns the path where the extension expects to find the browser executable.
func executablePath(
	path string,
	env env.LookupFunc,
	lookPath func(file string) (string, error), // os.LookPath
) (string, error) {
	// find the browser executable in the user provided path
	if path := strings.TrimSpace(path); path != "" {
		if _, err := lookPath(path); err == nil {

View on GitHub (pinned to 93accf6570)

Solutions

1. Install Google Chrome or Chromium on the host (e.g. apt-get install -y chromium chromium-driver on Debian/Ubuntu; apk add chromium on Alpine)
2. Point k6 at an existing binary: K6_BROWSER_EXECUTABLE_PATH=/usr/bin/chromium or the executablePath browser option
3. Or bypass local launch entirely with K6_BROWSER_WS_ENDPOINT pointing at an already-running Chrome
4. Verify detection first: which google-chrome google-chrome-stable chromium chromium-browser — if all fail, so will k6

Example fix

# before (Dockerfile with no browser)
FROM alpine
RUN k6 run script.js

# after
FROM alpine
RUN apk add --no-cache chromium chromium-swiftshader
ENV K6_BROWSER_EXECUTABLE_PATH=/usr/bin/chromium-browser

#!/bin/sh
# preflight: fail early with a clear message instead of mid-run
for b in google-chrome google-chrome-stable chromium chromium-browser; do
  command -v "$b" >/dev/null 2>&1 && exit 0
done
echo 'no chrome/chromium found; install one or set K6_BROWSER_EXECUTABLE_PATH / K6_BROWSER_WS_ENDPOINT' >&2
exit 1

When it happens

Trigger: Running a browser scenario on a fresh CI container (alpine, slim Debian) with no Chrome installed; a macOS/Linux box where Chrome was never installed or was uninstalled; a stripped image where chromium exists only under a non-standard name k6 does not probe.

Common situations: GitHub Actions/Docker images without a chrome setup step; company base images that deliberately exclude browsers; OS upgrades removing the chrome package; running on a server (no desktop) where Chrome was assumed present.

Related errors

• browser process ended unexpectedly
• k6 couldn't detect google chrome or a chromium-supported bro
• file does not exist: %s
• WebSocket endpoint cannot be empty
• finding browser executable: %w

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