What causes "file does not exist: %s" in grafana/k6?

Verify the path in the error exists: ls -l .

file does not exist: %s

Error message

file does not exist: %s

What it means

cmd.Start() returned an os.IsNotExist error: the executable k6 tried to launch (the Chromium binary from auto-detection or from K6_BROWSER_EXECUTABLE_PATH / BrowserOptions.ExecutablePath) does not exist at that path. The message echoes the exact path that was tried.

Source

Thrown at internal/js/modules/k6/browser/common/browser_process.go:177

	dataDir *storage.Dir, logger *log.Logger,
) (command, error) {
	cmd := exec.CommandContext(ctx, path, args...) //nolint:gosec
	killAfterParent(cmd)

	stdout, err := cmd.StdoutPipe()
	if err != nil {
		return command{}, fmt.Errorf("%w", err)
	}
	stderr, err := cmd.StderrPipe()
	if err != nil {
		return command{}, fmt.Errorf("%w", err)
	}

	// We must start the cmd before calling cmd.Wait, as otherwise the two
	// can run into a data race.
	err = cmd.Start()
	if os.IsNotExist(err) { //nolint:forbidigo
		return command{}, fmt.Errorf("file does not exist: %s", path)
	}
	if err != nil {
		return command{}, fmt.Errorf("%w", err)
	}
	if ctx.Err() != nil {
		return command{}, ContextErr(ctx)
	}

	done := make(chan struct{})
	go func() {
		// TODO: How to handle these errors?
		defer func() {
			if err := dataDir.Cleanup(); err != nil {
				logger.Errorf("browser", "cleaning up the user data directory: %v", err)
			}
			close(done)
		}()

View on GitHub (pinned to 93accf6570)

Solutions

Verify the path in the error exists: ls -l <path-from-error>.
Install Chrome/Chromium in the environment, or point K6_BROWSER_EXECUTABLE_PATH at the correct binary.
On CI, prefer an image that ships Chromium or install it in the pipeline before k6 runs.

Example fix

# before
export K6_BROWSER_EXECUTABLE_PATH=/usr/bin/chrome   # does not exist

# after
export K6_BROWSER_EXECUTABLE_PATH=/usr/bin/chromium-browser
# or install: apt-get install -y chromium

Defensive patterns

Strategy: validation

Validate before calling

# verify the browser binary exists before running k6
P="${K6_BROWSER_EXECUTABLE_PATH:-$(command -v chromium || command -v chromium-browser || command -v google-chrome)}"
[ -n "$P" ] && [ -x "$P" ] || { echo "browser executable missing: '$P'" >&2; exit 1; }

Try / catch

try {
  await launch();
} catch (e) {
  if (/file does not exist/.test(String(e))) {
    throw new Error('Install Chrome/Chromium or fix K6_BROWSER_EXECUTABLE_PATH');
  }
  throw e;
}

Prevention

Use CI images that ship Chromium or install it in the pipeline step before k6.
Pin K6_BROWSER_EXECUTABLE_PATH to a path you have verified with ls -l.
Include a browser-version echo step in CI to catch missing binaries early.

When it happens

Trigger: K6_BROWSER_EXECUTABLE_PATH points to a missing binary (typo'd path, binary not installed in the CI image); auto-detected chrome was uninstalled; a headless-shell download directory was moved or cleaned.

Common situations: Slim Docker images (alpine/distroless) with no Chrome installed; CI images where Chrome lives at a different path than locally; mounting a volume without the browser; wrong path separators on Windows.

Related errors

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