grafana/k6 · error · ErrChromeNotFoundAtPath

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 the given path: %s

What it means

This is the ErrChromeNotFoundAtPath sentinel (defined alongside ErrChromeNotInstalled) returned by executablePath() when the user explicitly provided a browser executable path but exec.LookPath could not resolve it. The '%s' suffix in the message echoes the offending path, and the sentinel supports errors.Is matching. Launch fails before spawning anything.

Source

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

	// 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 {
			return path, nil
		}
		return "", fmt.Errorf("%w: %s", ErrChromeNotFoundAtPath, path)
	}

	// find the browser executable in the default paths below
	paths := []string{
		// Unix-like
		"headless_shell",
		"headless-shell",
		"chromium",
		"chromium-browser",
		"google-chrome",
		"google-chrome-stable",
		"google-chrome-beta",
		"google-chrome-unstable",
		"/usr/bin/google-chrome",
		// Windows
		"chrome",
		"chrome.exe", // in case PATHEXT is misconfigured
		`C:\Program Files (x86)\Google\Chrome\Application\chrome.exe`,

View on GitHub (pinned to 93accf6570)

Solutions

Check the exact path from the error message: ls -l <path-from-error> on the machine/container running k6
Point executablePath at the real binary (e.g. /usr/bin/chromium or 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe'), or the headless_shell binary shipped in k6 browser images
Use an absolute path — relative paths resolve against k6's cwd, not the script location
If the binary exists, ensure it is executable (chmod +x) and matches the container architecture
Alternatively clear executablePath to let k6 auto-detect a system browser from its default list

Example fix

# before
export K6_BROWSER_EXECUTABLE_PATH=/usr/bin/google-chrome  # not present in this image

# after
export K6_BROWSER_EXECUTABLE_PATH=/usr/bin/chromium
# or omit it and rely on auto-detection

Defensive patterns

Strategy: validation

Try / catch

try {
  const browser = chromium.launch({ executablePath: CHROME });
} catch (e) {
  const m = String(e.message);
  if (m.includes("couldn't detect google chrome or a chromium-supported browser on the given path")) {
    throw new Error(`Chrome not found at ${CHROME}; verify the path inside the container running k6`);
  }
  throw e;
}

Prevention

Use absolute paths for executablePath; verify with ls in the same container
Derive the path from one env var used by both the Dockerfile and the test
If the path varies per environment, fall back to auto-detection by omitting executablePath

When it happens

Trigger: Setting options.executablePath / K6_BROWSER_EXECUTABLE_PATH to a nonexistent file; a relative path that does not resolve against k6's working directory; a path with a typo or wrong container mount; a path to a file without the executable bit or with wrong arch (LookPath behavior aside, unresolvable names fail); spaces or shell metacharacters in an unquoted path.

Common situations: Path works on the developer machine (/usr/bin/google-chrome) but the CI image keeps Chromium at /usr/bin/chromium; docker volume mounts the browser at a different path than the env var says; Windows paths with backslashes mangled by YAML escaping; pointing at the Chrome directory instead of the binary itself.

Related errors

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