{"record":{"id":"b64d908943a1a792","repo":"openclaw/openclaw","slug":"refs-aria-does-not-support-selector-frame-snapshot","errorCode":null,"errorMessage":"refs=aria does not support selector/frame snapshots yet.","messagePattern":"refs=aria does not support selector/frame snapshots yet\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"extensions/browser/src/browser/pw-tools-core.snapshot.ts","lineNumber":404,"sourceCode":"  delta?: { mode: RoleSnapshotIdentityMode; previousKeys?: ReadonlySet<string> };\n}): Promise<{\n  snapshot: string;\n  truncated?: boolean;\n  refs: Record<string, { role: string; name?: string; nth?: number }>;\n  stats: { lines: number; chars: number; refs: number; interactive: number };\n  newElements?: number;\n}> {\n  const page = await prepareSnapshotPageViaPlaywright({\n    cdpUrl: opts.cdpUrl,\n    targetId: opts.targetId,\n    ssrfPolicy: opts.ssrfPolicy,\n  });\n\n  const ariaSnapshotTimeout = resolveSnapshotTimeoutMs(opts.timeoutMs);\n\n  if (opts.refsMode === \"aria\") {\n    if (normalizeOptionalString(opts.selector) || normalizeOptionalString(opts.frameSelector)) {\n      throw new Error(\"refs=aria does not support selector/frame snapshots yet.\");\n    }\n    return await withSnapshotFrameGuard({\n      page,\n      run: async (isFrameCurrent) => {\n        const snapshot = await page.ariaSnapshot({\n          mode: \"ai\",\n          timeout: ariaSnapshotTimeout,\n        });\n        const built = buildRoleSnapshotFromAiSnapshot(snapshot, opts.options);\n        return await finalizeRoleSnapshotViaPlaywright({\n          page,\n          cdpUrl: opts.cdpUrl,\n          targetId: opts.targetId,\n          isFrameCurrent,\n          built,\n          mode: \"aria\",\n          urls: opts.urls,\n          maxChars: opts.maxChars,","sourceCodeStart":386,"sourceCodeEnd":422,"githubUrl":"https://github.com/openclaw/openclaw/blob/01804a75319da4b69c9ab98ceaa30477e22b8c0b/extensions/browser/src/browser/pw-tools-core.snapshot.ts#L386-L422","documentation":"Thrown when the caller requests refsMode='aria' together with a selector or frameSelector parameter. The aria refs mode uses Playwright's page-wide AI aria snapshot (page.ariaSnapshot with mode 'ai'), which captures the entire page accessibility tree and assigns refs across all frames. Scoping aria snapshots to a CSS selector or specific iframe is not implemented yet, so the combination is rejected rather than silently producing incomplete output.","triggerScenarios":"Calling snapshotViaPlaywright with opts.refsMode='aria' and a non-empty opts.selector or opts.frameSelector.","commonSituations":"Models or tools that default to aria refs but also pass a selector for scoping. Configs that set both parameters without knowing they are mutually exclusive. Code that reuses a parameter object across different snapshot modes.","solutions":["If you need aria refs, omit the selector and frameSelector parameters to capture a page-wide snapshot.","If you need selector or frame scoping, use refsMode='role' (the default role-based snapshot) instead of 'aria'.","Run two snapshots: one page-wide aria snapshot for refs, then a role snapshot scoped to the selector if detailed structure is needed."],"exampleFix":"// before\nawait snapshotViaPlaywright({\n  cdpUrl, targetId,\n  refsMode: \"aria\",\n  selector: \"#content\",\n});\n// after — use role refs for selector-scoped snapshots\nawait snapshotViaPlaywright({\n  cdpUrl, targetId,\n  refsMode: \"role\",\n  selector: \"#content\",\n});","handlingStrategy":"validation","validationCode":"function validateSnapshotOpts(opts: { refsMode?: string; selector?: string; frameSelector?: string }): void {\n  if (opts.refsMode === \"aria\") {\n    if ((opts.selector ?? \"\").trim() || (opts.frameSelector ?? \"\").trim()) {\n      throw new Error(\"refsMode=aria cannot be combined with selector or frameSelector; use refsMode=role instead\");\n    }\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never combine refsMode='aria' with selector or frameSelector parameters.","Use refsMode='role' for selector-scoped or frame-scoped snapshots.","Document the mutual exclusivity of these parameters in tool descriptions."],"tags":["browser","snapshot","aria","selector","config","unsupported"],"backgroundTag":null,"analyzedSha":"01804a75319da4b69c9ab98ceaa30477e22b8c0b","analyzedAt":"2026-08-12T04:37:58.197Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}