grafana/k6 · error

page.route(' ')

Error message

page.route('%s'): %w

What it means

General wrapper for failures inside a page.route(pattern, handler) interception: the JavaScript handler callback raised an error (anything other than context cancellation, which gets its own message). The error from executing the queued handler task is wrapped with the route pattern for context.

Solutions

1. Wrap the handler body in try/catch and call route.abort() or route.continue() in the catch branch so the browser request never hangs.
2. Verify every method used exists on the mapped k6 Route object (fulfill, abort, continue, request).
3. Log the error inside the handler to identify which intercepted URL fails.
4. Narrow the route pattern so only intended requests invoke the handler.

Example fix

// before
await page.route('**/api/config', route => route.fulfill({ body: JSON.stringify(cfg.payload) }));

// after
await page.route('**/api/config', async route => {
  try { await route.fulfill({ body: JSON.stringify(cfg.payload) }); }
  catch (e) { await route.continue(); }
});

await page.route('**/api/config', async (route) => {
  try {
    await route.fulfill({ status: 200, body: JSON.stringify(payload) });
  } catch (e) {
    console.log('route handler error, passing through:', e.message);
    await route.continue();
  }
});

When it happens

Trigger: An exception thrown inside the route handler (TypeError on the mapped Route object, calling a non-existent method); handler code referencing out-of-scope variables that became undefined; route.fulfill() given a malformed body type causing a JS-level throw.

Common situations: Handlers assuming Playwright's route.request() chaining; mocking responses where the body/headers construction throws; handlers that forget to settle the route and also throw on later cleanup; typos in route.continue()/fulfill/abort names.

Related errors

• executing page.on(' ') handler
• executing waitForEvent predicate
• page.route(' '): iteration ended before route completed
• evaluate requires a page function
• evaluateHandle requires a page function

AI-assisted analysis of grafana/k6@8d06114777 (2026-08-18). Data as JSON: /api/errors/d488c45a3882a634. Report an issue: GitHub.

Appendix: source

Thrown at internal/js/modules/k6/browser/browser/page_mapping.go:986

}

// mapPageRoute maps the requested page.route event to the Sobek runtime.
func mapPageRoute(vu moduleVU, p *common.Page) func(sobek.Value, sobek.Callable) (*sobek.Promise, error) {
	return func(path sobek.Value, cb sobek.Callable) (*sobek.Promise, error) {
		ctx := vu.Context()

		ppath := parseStringOrRegex(path, false)
		tq := vu.get(ctx, p.TargetID())

		route := func(r *common.Route) error {
			_, err := queueTask(ctx, tq, func() (any, error) {
				return cb(sobek.Undefined(), vu.Runtime().ToValue(mapRoute(vu, r)))
			})()
			if errors.Is(err, context.Canceled) {
				return fmt.Errorf("page.route('%s'): iteration ended before route completed", path)
			}
			if err != nil {
				return fmt.Errorf("page.route('%s'): %w", path, err)
			}
			return nil
		}

		return promise(vu, func() (any, error) {
			return nil, p.Route(ppath, route, newRegExMatcher(ctx, vu, tq))
		}), nil
	}
}

func mapWaitForURL(rt *sobek.Runtime, vu moduleVU, target interface {
	Timeout() time.Duration
	WaitForURL(urlPattern string, opts *common.FrameWaitForURLOptions, rm common.RegExMatcher) error
}, url sobek.Value, opts sobek.Value,
) (*sobek.Promise, error) {
	if k6common.IsNullish(url) {
		return nil, errors.New("missing required argument 'url'")
	}

View on GitHub (pinned to 8d06114777)