browser process shutdown unexpectedly before establishing a

Error message

browser process shutdown unexpectedly before establishing a connection: %w

What it means

The devToolsURLParser scans the browser's stderr for the DevTools websocket endpoint. If the pipe comes back fs.ErrClosed, the browser process exited before ever printing its ws endpoint, and k6 wraps that as an unexpected pre-connection shutdown. This is the classic 'browser died at launch' error.

Source

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

		if i := strings.Index(line, "] "); i > 0 {
			p.errs = append(p.errs, errors.New(line[i+2:]))
		}
	}

	return p.url == ""
}

func (p *devToolsURLParser) err() error {
	if p.url != "" {
		return io.EOF
	}
	if len(p.errs) > 0 {
		return p.errs[0]
	}

	err := p.sc.Err()
	if errors.Is(err, fs.ErrClosed) {
		return fmt.Errorf("browser process shutdown unexpectedly before establishing a connection: %w", err)
	}
	if err != nil {
		return err //nolint:wrapcheck
	}

	return nil
}

View on GitHub (pinned to 93accf6570)

Solutions

Run the same binary manually with the same arguments (add --headless --dump-dom about:blank) and read its stderr — it names the real problem.
On slim images, install Chromium runtime deps (libnss3, libatk-bridge2.0-0, libdrm, libxkbcommon, ...) or use a full image.
In root containers add --no-sandbox via K6_BROWSER_ARGUMENTS (or a non-root user).
Remove recently added custom K6_BROWSER_ARGUMENTS flags one by one to find the bad one.
Ensure TMPDIR/disk has space for the per-launch user data dir.

Example fix

# before
# slim CI image, chrome exits silently at launch
k6 run test.js  # browser process shutdown unexpectedly...

# after
apt-get install -y libnss3 libatk-bridge2.0-0 libdrm libxkbcommon libgbm1
k6 run test.js

Defensive patterns

Strategy: validation

Validate before calling

# CI pre-flight: launch the browser once with k6's flags and confirm it prints a DevTools endpoint
CHROME="${K6_BROWSER_EXECUTABLE_PATH:-chromium}"
timeout 10 "$CHROME" --headless --no-sandbox --disable-gpu --dump-dom about:blank >/dev/null 2>/tmp/chrome-smoke.err \
  || { echo 'browser fails to start:'; cat /tmp/chrome-smoke.err; exit 1; }

Prevention

Run the browser binary manually with the same K6_BROWSER_ARGUMENTS whenever flags change.
Use images with Chromium's shared-library deps or install them explicitly.
Add --no-sandbox when running as root in containers; keep the user data dir on writable storage.

When it happens

Trigger: Chrome exits immediately on startup: missing shared libraries (libnss3/libatk on slim images), invalid flags passed via K6_BROWSER_ARGUMENTS, sandbox failure in root containers (no --no-sandbox), incompatible/very old Chromium build, or the user-data-dir being unwritable.

Common situations: Running headless Chromium on minimal CI images (alpine, debian-slim) without lib dependencies; passing K6_BROWSER_ARGUMENTS="--headless=new --bad-flag"; running as root in Docker without --no-sandbox; disk-full temp directory for the user data dir.

Related errors

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