grafana/k6 · critical · ErrFatal

fatal error

Error message

fatal error

What it means

k6error.ErrFatal (internal.go:11-15) is a sentinel error, not a user-facing failure by itself. Browser-module code wraps it around conditions that are deterministic — if the iteration ran again it would fail identically — so the mapping layer aborts the entire test run instead of just the current iteration. You always see it wrapped with the real cause; read the accompanying message to find the underlying failure.

Source

Thrown at internal/js/modules/k6/browser/k6error/internal.go:15

// Package k6error contains ErrFatal.
package k6error

import (
	"errors"
)

// ErrFatal should be wrapped into an error
// to signal to the mapping layer that the error
// is a fatal error and we should abort the whole
// test run, not just the current iteration. It
// should be used in cases where if the iteration
// ran again then there's a 100% chance that it
// will end up running into the same error.
var ErrFatal = errors.New("fatal error")

View on GitHub (pinned to 01ffac6f24)

Solutions

1. Read the wrapped cause in the full error text — it names the actual failing component; fix that first
2. Verify the browser setup: installed chromium, K6_BROWSER_EXECUTABLE path, or a reachable remote endpoint
3. Check k6/browser version compatibility per the k6 browser docs and upgrade k6 if behind
4. In CI, raise container memory and /dev/shm size (e.g. docker --shm-size=1g) to prevent chromium crashes
5. Do not blind-retry: by design the same run would fail identically until the environment is fixed

// Fail fast on environment problems before the run starts
import { checkSetup } from './setup.js';
await checkSetup(); // asserts chromium present / endpoint reachable

// Fatal errors abort the run; catch only to log/teardown, not to continue
try {
  await page.goto(url);
} catch (e) {
  console.error('fatal:', e.message); // read the wrapped cause
  throw e; // rethrow — rerunning unchanged will fail identically
}

When it happens

Trigger: Internal browser code returning fmt.Errorf wrapping k6error.ErrFatal — typically unrecoverable conditions such as the browser process/connection dying mid-run. The mapping layer detects the sentinel and escalates from iteration-abort to run-abort.

Common situations: Chromium binary missing or version-incompatible with the installed k6; remote browser (ws:// CDP endpoint) unreachable or dropping; browser process crash due to tiny /dev/shm or memory limits in CI containers; browser context/page invalidation after a crash.

Related errors

• on create page event failed to return a page: %w
• Unexpected end of selector while parsing selector `${selecto
• Error while parsing selector `${selector}` - unexpected symb
• Error while parsing selector `${selector}`: ${e.message}
• Error while parsing selector `${selector}` - cannot use ${op

AI-assisted analysis of grafana/k6@01ffac6f24 (2026-08-18). Data as JSON: /api/errors/94747f5fba5adc1e. Report an issue: GitHub.