What causes "creating url matcher for path %s: %w" in grafana/k6?

If using the public page.route API, upgrade k6 — this indicates an internal wiring bug, not a script problem

creating url matcher for path %s: %w

Error message

creating url matcher for path %s: %w

What it means

Page.Route builds a URL matcher via newPatternMatcher, which only fails at creation when a non-quoted (regex) pattern is supplied but no regex matcher function is available ('regex matcher must be provided'). In normal k6 operation the Sobek-based matcher is always provided, so this creation error indicates an internal misconfiguration; regex compile/match problems surface later, at request-matching time, not here.

Source

Thrown at internal/js/modules/k6/browser/common/page.go:1370

	return nm.extraHTTPHeaders["referer"]
}

// Route registers a handler to be executed for a given request path
func (p *Page) Route(path string, cb RouteHandlerCallback, rm RegExMatcher) error {
	p.logger.Debugf("Page:Route", "sid:%v path:%s", p.sessionID(), path)

	p.routesMu.Lock()
	defer p.routesMu.Unlock()
	if len(p.routes) == 0 {
		err := p.mainFrameSession.updateRequestInterception(true)
		if err != nil {
			return err
		}
	}

	matcher, err := newPatternMatcher(path, rm)
	if err != nil {
		return fmt.Errorf("creating url matcher for path %s: %w", path, err)
	}

	routeHandler := NewRouteHandler(path, cb, matcher)
	// Append new route at the beginning of the slice as, when several routes match the given pattern,
	// they will run in the opposite order to their registration.
	p.routes = append([]*RouteHandler{routeHandler}, p.routes...)

	return nil
}

// Unroute removes the route(s) for the specified URL pattern.
// If multiple routes match the same URL pattern, all of them are removed.
func (p *Page) Unroute(path string) error {
	p.logger.Debugf("Page:Unroute", "sid:%v path:%s", p.sessionID(), path)

	p.routesMu.Lock()
	defer p.routesMu.Unlock()

View on GitHub (pinned to 93accf6570)

Solutions

If using the public page.route API, upgrade k6 — this indicates an internal wiring bug, not a script problem
Prefer quoted exact URLs ('https://host/path') or simple glob patterns, which never need the regex matcher
Report the issue with the pattern and k6 version if reproducible on the current release

Example fix

// before
await page.route(/api\/v1\//, handler); // regex path, matcher-dependent

// after
await page.route('**/api/v1/**', handler);

Defensive patterns

Strategy: try-catch

Validate before calling

if (typeof pattern !== 'string' || pattern.length === 0) throw new Error('route pattern must be a non-empty string');

Try / catch

try {
  await page.route(pattern, handler);
} catch (e) {
  if (/creating url matcher/.test(e.message)) { await page.route('**/' + pattern + '/**', handler); }
  else throw e;
}

Prevention

Prefer glob patterns ('**/api/**') or quoted exact URLs over regex strings
If this fires on the public API, report a k6 bug — matcher wiring should never be nil

When it happens

Trigger: Calling page.route(pattern, handler) with a regex-style pattern in a code path where the browser's regex matcher was not wired in (internal/API misuse), rather than via the normal k6 script surface.

Common situations: Essentially unseen by JS script authors; appears only in programs embedding the browser module or after internal refactors broke matcher injection.

Related errors

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