{"record":{"id":"283aec862a51f7e8","repo":"grafana/k6","slug":"unexpected-document-handle-type-t","errorCode":null,"errorMessage":"unexpected document handle type: %T","messagePattern":"unexpected document handle type: %T","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"internal/js/modules/k6/browser/common/frame.go","lineNumber":296,"sourceCode":"func (f *Frame) newDocumentHandle() (*ElementHandle, error) {\n\tresult, err := f.evaluate(\n\t\tf.ctx,\n\t\tmainWorld,\n\t\tevalOptions{\n\t\t\tforceCallable: false,\n\t\t\treturnByValue: false,\n\t\t},\n\t\t\"document\",\n\t)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"getting document element handle: %w\", err)\n\t}\n\tif result == nil {\n\t\treturn nil, fmt.Errorf(\"document element handle is nil\")\n\t}\n\tdh, ok := result.(*ElementHandle)\n\tif !ok {\n\t\treturn nil, fmt.Errorf(\"unexpected document handle type: %T\", result)\n\t}\n\n\treturn dh, nil\n}\n\nfunc (f *Frame) hasContext(world executionWorld) bool {\n\tf.executionContextMu.RLock()\n\tdefer f.executionContextMu.RUnlock()\n\n\treturn f.executionContexts[world] != nil\n}\n\nfunc (f *Frame) hasLifecycleEventFired(event LifecycleEvent) bool {\n\tf.lifecycleEventsMu.RLock()\n\tdefer f.lifecycleEventsMu.RUnlock()\n\n\treturn f.lifecycleEvents[event]\n}","sourceCodeStart":278,"sourceCodeEnd":314,"githubUrl":"https://github.com/grafana/k6/blob/93accf6570dcd306ca5e99cc44c393ee3797761b/internal/js/modules/k6/browser/common/frame.go#L278-L314","documentation":"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.","triggerScenarios":"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.","commonSituations":"Rare; if seen, it is on unusual pages (e.g. non-standard document bindings) or pre-release k6 builds.","solutions":["Update k6 to the latest patch release","Reproduce minimally and report to the k6 browser module maintainers","As a workaround, retry the failing operation once"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  el = await page.waitForSelector('#x');\n} catch (e) {\n  if (/unexpected document handle type/.test(e.message)) {\n    // internal invariant break: retry once, then report upstream with k6 version\n  } else throw e;\n}","preventionTips":["Keep k6 updated to the latest patch release","Pin k6 versions in CI for reproducibility","Report occurrences with a minimal reproducer"],"tags":["browser","internal","invariant"],"backgroundTag":null,"analyzedSha":"93accf6570dcd306ca5e99cc44c393ee3797761b","analyzedAt":"2026-08-15T21:23:27.118Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}