grafana/k6 · warning

unexpected document handle type: %T

Error message

unexpected document handle type: %T

What it means

After evaluating 'document' with returnByValue=false, k6 expects an *ElementHandle (a node) but got a different Go type. 'document' in a browser always resolves to a node, so reaching this branch implies an internal invariant break — the evaluation returned a non-node object — not something the script did wrong. In practice it is nearly unreachable for users.

Source

Thrown at internal/js/modules/k6/browser/common/frame.go:296

func (f *Frame) newDocumentHandle() (*ElementHandle, error) {
	result, err := f.evaluate(
		f.ctx,
		mainWorld,
		evalOptions{
			forceCallable: false,
			returnByValue: false,
		},
		"document",
	)
	if err != nil {
		return nil, fmt.Errorf("getting document element handle: %w", err)
	}
	if result == nil {
		return nil, fmt.Errorf("document element handle is nil")
	}
	dh, ok := result.(*ElementHandle)
	if !ok {
		return nil, fmt.Errorf("unexpected document handle type: %T", result)
	}

	return dh, nil
}

func (f *Frame) hasContext(world executionWorld) bool {
	f.executionContextMu.RLock()
	defer f.executionContextMu.RUnlock()

	return f.executionContexts[world] != nil
}

func (f *Frame) hasLifecycleEventFired(event LifecycleEvent) bool {
	f.lifecycleEventsMu.RLock()
	defer f.lifecycleEventsMu.RUnlock()

	return f.lifecycleEvents[event]
}

View on GitHub (pinned to 93accf6570)

Solutions

1. Update k6 to the latest patch release
2. Reproduce minimally and report to the k6 browser module maintainers
3. As a workaround, retry the failing operation once

try {
  el = await page.waitForSelector('#x');
} catch (e) {
  if (/unexpected document handle type/.test(e.message)) {
    // internal invariant break: retry once, then report upstream with k6 version
  } else throw e;
}

When it happens

Trigger: An internal k6 bug or version skew causing the 'document' expression to resolve to a non-node remote object; not reproducible through normal script inputs.

Common situations: Rare; if seen, it is on unusual pages (e.g. non-standard document bindings) or pre-release k6 builds.

Related errors

• querying selector %q, wrong type %T
• getting element handle for selector %q: %w
• parsing element index %q for selector %q: %w
• unpacking selected options: %w
• getting text content of element: unexpected type %T (expecti

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