grafana/k6 · critical · errBrowserNotFoundInRegistry

browser not found in registry. make sure to set browser type

Error message

browser not found in registry. make sure to set browser type option in scenario definition in order to use the browser module

What it means

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.

Source

Thrown at internal/js/modules/k6/browser/browser/registry.go:33

	"go.opentelemetry.io/otel/attribute"
	oteltrace "go.opentelemetry.io/otel/trace"

	"go.k6.io/k6/v2/internal/js/modules/k6/browser/chromium"
	"go.k6.io/k6/v2/internal/js/modules/k6/browser/common"
	"go.k6.io/k6/v2/internal/js/modules/k6/browser/env"
	"go.k6.io/k6/v2/internal/js/modules/k6/browser/k6ext"
	browsertrace "go.k6.io/k6/v2/internal/js/modules/k6/browser/trace"
	"go.k6.io/k6/v2/internal/js/taskqueue"

	k6event "go.k6.io/k6/v2/internal/event"
	k6modules "go.k6.io/k6/v2/js/modules"
)

// errBrowserNotFoundInRegistry indicates that the browser instance
// for the iteration, which should have been initialized as a result
// of the IterStart event, has not been found in the registry. This
// might happen if browser type option is not set in scenario definition.
var errBrowserNotFoundInRegistry = errors.New("browser not found in registry. " +
	"make sure to set browser type option in scenario definition in order to use the browser module")

// pidRegistry keeps track of the launched browser process IDs.
type pidRegistry struct {
	mu  sync.RWMutex
	ids []int
}

// registerPid registers the launched browser process ID.
func (r *pidRegistry) registerPid(pid int) {
	r.mu.Lock()
	defer r.mu.Unlock()

	r.ids = append(r.ids, pid)
}

// Pids returns the launched browser process IDs.
func (r *pidRegistry) Pids() []int {

View on GitHub (pinned to 93accf6570)

Solutions

1. 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' } } } } }
2. If you have multiple scenarios, add options.browser.type to every scenario that executes browser code
3. Verify the options block is actually exported (export const options) and the script is run with k6 run

Example fix

// before
import { browser } from 'k6/browser';
export default async function () {
  const page = await browser.newPage(); // throws
}

// after
import { browser } from 'k6/browser';
export const options = {
  scenarios: {
    browser: {
      executor: 'constant-vus',
      vus: 1,
      duration: '10s',
      options: { browser: { type: 'chromium' } },
    },
  },
};
export default async function () {
  const page = await browser.newPage();
  await page.goto('https://k6.io/');
}

import { browser } from 'k6/browser';

// The check happens at config level: this options block must exist and every
// scenario that runs browser code needs the browser type option.
export const options = {
  scenarios: {
    ui: { options: { browser: { type: 'chromium' } } },
  },
};

export default async function () {
  if (!browser) throw new Error('browser module unavailable — check scenario options');
  const page = await browser.newPage();
  // ...
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• missing required url
• WebSocket endpoint cannot be empty
• k6 couldn't detect google chrome or a chromium-supported bro
• browser type option must be set
• missing presigned url in response body

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