{"record":{"id":"94747f5fba5adc1e","repo":"grafana/k6","slug":"fatal-error","errorCode":null,"errorMessage":"fatal error","messagePattern":"fatal error","errorType":"exception","errorClass":"ErrFatal","httpStatus":null,"severity":"critical","filePath":"internal/js/modules/k6/browser/k6error/internal.go","lineNumber":15,"sourceCode":"// Package k6error contains ErrFatal.\npackage k6error\n\nimport (\n\t\"errors\"\n)\n\n// ErrFatal should be wrapped into an error\n// to signal to the mapping layer that the error\n// is a fatal error and we should abort the whole\n// test run, not just the current iteration. It\n// should be used in cases where if the iteration\n// ran again then there's a 100% chance that it\n// will end up running into the same error.\nvar ErrFatal = errors.New(\"fatal error\")\n","sourceCodeStart":1,"sourceCodeEnd":16,"githubUrl":"https://github.com/grafana/k6/blob/01ffac6f245854c1b8adc6a69857c76a15f90022/internal/js/modules/k6/browser/k6error/internal.go#L1-L16","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the wrapped cause in the full error text — it names the actual failing component; fix that first","Verify the browser setup: installed chromium, K6_BROWSER_EXECUTABLE path, or a reachable remote endpoint","Check k6/browser version compatibility per the k6 browser docs and upgrade k6 if behind","In CI, raise container memory and /dev/shm size (e.g. docker --shm-size=1g) to prevent chromium crashes","Do not blind-retry: by design the same run would fail identically until the environment is fixed"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Fail fast on environment problems before the run starts\nimport { checkSetup } from './setup.js';\nawait checkSetup(); // asserts chromium present / endpoint reachable","typeGuard":null,"tryCatchPattern":"// Fatal errors abort the run; catch only to log/teardown, not to continue\ntry {\n  await page.goto(url);\n} catch (e) {\n  console.error('fatal:', e.message); // read the wrapped cause\n  throw e; // rethrow — rerunning unchanged will fail identically\n}","preventionTips":["Verify chromium or the remote CDP endpoint in a setup step before iterations","Pin compatible k6 and browser versions per the k6 browser docs","Give CI containers enough memory and /dev/shm for chromium","Read the wrapped cause message; the sentinel itself carries no detail"],"tags":["browser","fatal","abort","k6error"],"backgroundTag":"fatal-unrecoverable-error","analyzedSha":"01ffac6f245854c1b8adc6a69857c76a15f90022","analyzedAt":"2026-08-18T03:05:52.393Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}