{"record":{"id":"5e779d13e0a73e28","repo":"grafana/k6","slug":"browser-not-found-in-registry-make-sure-to-set-br","errorCode":null,"errorMessage":"browser not found in registry. make sure to set browser type option in scenario definition in order to use the browser module","messagePattern":"browser not found in registry\\. make sure to set browser type option in scenario definition in order to use the browser module","errorType":"exception","errorClass":"errBrowserNotFoundInRegistry","httpStatus":null,"severity":"error","filePath":"internal/js/modules/k6/browser/browser/registry.go","lineNumber":33,"sourceCode":"\t\"go.opentelemetry.io/otel/attribute\"\n\toteltrace \"go.opentelemetry.io/otel/trace\"\n\n\t\"go.k6.io/k6/v2/internal/js/modules/k6/browser/chromium\"\n\t\"go.k6.io/k6/v2/internal/js/modules/k6/browser/common\"\n\t\"go.k6.io/k6/v2/internal/js/modules/k6/browser/env\"\n\t\"go.k6.io/k6/v2/internal/js/modules/k6/browser/k6ext\"\n\tbrowsertrace \"go.k6.io/k6/v2/internal/js/modules/k6/browser/trace\"\n\t\"go.k6.io/k6/v2/internal/js/taskqueue\"\n\n\tk6event \"go.k6.io/k6/v2/internal/event\"\n\tk6modules \"go.k6.io/k6/v2/js/modules\"\n)\n\n// errBrowserNotFoundInRegistry indicates that the browser instance\n// for the iteration, which should have been initialized as a result\n// of the IterStart event, has not been found in the registry. This\n// might happen if browser type option is not set in scenario definition.\nvar errBrowserNotFoundInRegistry = errors.New(\"browser not found in registry. \" +\n\t\"make sure to set browser type option in scenario definition in order to use the browser module\")\n\n// pidRegistry keeps track of the launched browser process IDs.\ntype pidRegistry struct {\n\tmu  sync.RWMutex\n\tids []int\n}\n\n// registerPid registers the launched browser process ID.\nfunc (r *pidRegistry) registerPid(pid int) {\n\tr.mu.Lock()\n\tdefer r.mu.Unlock()\n\n\tr.ids = append(r.ids, pid)\n}\n\n// Pids returns the launched browser process IDs.\nfunc (r *pidRegistry) Pids() []int {","sourceCodeStart":15,"sourceCodeEnd":51,"githubUrl":"https://github.com/grafana/k6/blob/01ffac6f245854c1b8adc6a69857c76a15f90022/internal/js/modules/k6/browser/browser/registry.go#L15-L51","documentation":"k6 pre-launches one browser per VU iteration on the IterStart event and stores it in an internal registry keyed by iteration ID; the browser module fetches it lazily via getBrowser (internal/js/modules/k6/browser/browser/registry.go:396). If nothing was launched — almost always because no browser type option was configured for the scenario — the lookup returns errBrowserNotFoundInRegistry. It is k6's guard against using k6/browser without the required options.","triggerScenarios":"Importing k6/browser and calling chromium/browser() (or any page API) in a script whose options block lacks `browser: { type: 'chromium' }` — at scenario level or top level; browser options defined in one scenario while the browser code runs in another; a failed per-iteration browser launch leaving the registry empty.","commonSituations":"Browser examples copied from docs with the options block dropped; migration from the old k6/x/browser extension where the option was not required; options refactor that moved browser config out of the scenario; running a very old k6 binary that does not pre-launch browsers.","solutions":["Set the browser type option in the scenario: `export const options = { scenarios: { ui: { executor: 'shared-iterations', options: { browser: { type: 'chromium' } } } } }`","Or set it top-level so every scenario inherits it: `export const options = { browser: { type: 'chromium' } }`","Import from 'k6/browser' (not 'k6/x/browser') and verify you run a modern k6 binary (browser module requires k6 >= 0.43; v1.x recommended)","Check k6 output above this error — a failed browser launch for the iteration produces the same missing-registry lookup"],"exampleFix":"// before\nimport { browser } from 'k6/browser';\nexport default async function () {\n  const page = await browser.newPage(); // no browser type configured\n}\n\n// after\nimport { browser } from 'k6/browser';\nexport const options = {\n  scenarios: {\n    ui: { executor: 'shared-iterations', options: { browser: { type: 'chromium' } } },\n  },\n};\nexport default async function () {\n  const page = await browser.newPage();\n}","handlingStrategy":"validation","validationCode":"// k6 options are static — declare them unconditionally next to the browser import\nimport { browser } from 'k6/browser';\nexport const options = {\n  scenarios: {\n    ui: { executor: 'shared-iterations', vus: 1, options: { browser: { type: 'chromium' } } },\n  },\n};","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always ship a browser type option (scenario-level or top-level) together with any k6/browser import","Keep the options block and the browser import in the same review unit so they never drift apart","Import from 'k6/browser', not 'k6/x/browser', and pin a modern k6 binary in CI","Treat 'browser not found in registry' in review as a signal the options block was dropped"],"tags":["browser","configuration","scenario-options","startup"],"backgroundTag":"missing-required-config","analyzedSha":"01ffac6f245854c1b8adc6a69857c76a15f90022","analyzedAt":"2026-08-18T03:05:52.393Z","contentChangedAt":"2026-08-18T03:05:52.393Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}