grafana/k6 · error

browser type option must be set

Error message

browser type option must be set

What it means

BrowserOptions.Parse reads the type field from the browser options object and requires it: only 'chromium' is supported, so a missing type key returns this error (a present-but-wrong value gives 'unsupported browser type: X' instead). This fires when browser options exist but the mandatory type was not declared.

Source

Thrown at internal/js/modules/k6/browser/common/browser_options.go:67

	return &BrowserOptions{
		Headless:          true,
		LogCategoryFilter: ".*",
		Timeout:           DefaultTimeout,
		isRemoteBrowser:   true,
	}
}

// Parse parses browser options from a JS object.
func (bo *BrowserOptions) Parse(
	ctx context.Context, logger *log.Logger, opts map[string]any, envLookup env.LookupFunc,
) error {
	// Parse opts
	bt, ok := opts[optType]
	// Only 'chromium' is supported by now, so return error
	// if type option is not set, or if it's set and its value
	// is different than 'chromium'
	if !ok {
		return errors.New("browser type option must be set")
	}
	if bt != "chromium" {
		return fmt.Errorf("unsupported browser type: %s", bt)
	}

	// Parse env
	envOpts := [...]string{
		env.BrowserArguments,
		env.BrowserEnableDebugging,
		env.BrowserExecutablePath,
		env.BrowserHeadless,
		env.BrowserIgnoreDefaultArgs,
		env.LogCategoryFilter,
		env.BrowserGlobalTimeout,
	}

	for _, e := range envOpts {
		ev, ok := envLookup(e)

View on GitHub (pinned to 93accf6570)

Solutions

1. Add type: 'chromium' inside the browser options at the right nesting: scenarios.ui.options.browser.type = 'chromium'
2. Double-check the exact key and nesting against the working snippet in the docs; the value must be the literal string 'chromium'
3. If you meant to run without a local browser, use the WS-endpoint configuration instead of dropping type

Example fix

// before
export const options = {
  scenarios: { ui: { options: { browser: { headless: true } } } },
};

// after
export const options = {
  scenarios: { ui: { options: { browser: { type: 'chromium', headless: true } } } },
};

// Fail loudly at parse time instead of deep inside options parsing:
const browserOpts = { headless: true, ...overrides };
if (!('type' in browserOpts) || browserOpts.type !== 'chromium') {
  throw new Error("browser options must include type: 'chromium'");
}

function isValidBrowserOptions(o) {
  return o != null && typeof o === 'object' && o.type === 'chromium';
}

When it happens

Trigger: Exporting options.browser = { headless: true } without type; setting only env tuning vars (K6_BROWSER_HEADLESS etc.) while the scenario options carry no type; misspelling the key ('Type', 'browserType') or nesting it incorrectly so the map k6 receives has no 'type' key.

Common situations: Users adding headless/env tweaks to an options block that never had a type; restructured options where browser options moved between top-level and scenario scope; generated config from older k6 examples.

Related errors

• missing required url
• missing required argument 'altText'
• missing required argument 'label'
• missing required argument 'placeholder'
• missing required argument 'role'

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