{"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":"critical","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/93accf6570dcd306ca5e99cc44c393ee3797761b/internal/js/modules/k6/browser/browser/registry.go#L15-L51","documentation":"The browser module keeps a per-iteration registry of live browser instances, initialized when the scenario's IterStart event fires. errBrowserNotFoundInRegistry is returned when a browser API (browser.newPage, page.goto, ...) is called but no browser was initialized for this iteration — the canonical cause being that the scenario does not declare the browser type option, so k6 never launched/attached a browser for these VUs.","triggerScenarios":"Using the browser module in a script whose exported options lack scenarios...options.browser.type: 'chromium'; calling browser APIs from a scenario that was defined without browser options; running browser code in a shared helper invoked by a plain HTTP scenario.","commonSituations":"New users porting Playwright scripts and missing k6's required scenario options; multi-scenario setups where one scenario has the browser options and another does not; examples/tutorials run without the options block; moving code into a shared function called by all scenarios.","solutions":["Add browser options to the scenario in your exported options: export const options = { scenarios: { browser: { executor: 'constant-vus', vus: 1, duration: '10s', options: { browser: { type: 'chromium' } } } } }","If you have multiple scenarios, add options.browser.type to every scenario that executes browser code","Verify the options block is actually exported (export const options) and the script is run with k6 run"],"exampleFix":"// before\nimport { browser } from 'k6/browser';\nexport default async function () {\n  const page = await browser.newPage(); // throws\n}\n\n// after\nimport { browser } from 'k6/browser';\nexport const options = {\n  scenarios: {\n    browser: {\n      executor: 'constant-vus',\n      vus: 1,\n      duration: '10s',\n      options: { browser: { type: 'chromium' } },\n    },\n  },\n};\nexport default async function () {\n  const page = await browser.newPage();\n  await page.goto('https://k6.io/');\n}","handlingStrategy":"validation","validationCode":"import { browser } from 'k6/browser';\n\n// The check happens at config level: this options block must exist and every\n// scenario that runs browser code needs the browser type option.\nexport const options = {\n  scenarios: {\n    ui: { options: { browser: { type: 'chromium' } } },\n  },\n};","typeGuard":null,"tryCatchPattern":"export default async function () {\n  if (!browser) throw new Error('browser module unavailable — check scenario options');\n  const page = await browser.newPage();\n  // ...\n}","preventionTips":["Always export the canonical scenario options block when importing k6/browser — treat it as part of the import","In multi-scenario files, add options.browser.type to every scenario whose code path touches browser APIs","Keep browser code out of shared helpers called by non-browser scenarios"],"tags":["browser","configuration","scenario-options","registry"],"backgroundTag":null,"analyzedSha":"93accf6570dcd306ca5e99cc44c393ee3797761b","analyzedAt":"2026-08-15T21:23:27.118Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}