refs=aria does not support selector/frame snapshots yet.

Error message

refs=aria does not support selector/frame snapshots yet.

What it means

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.

Source

Thrown at extensions/browser/src/browser/pw-tools-core.snapshot.ts:404

  delta?: { mode: RoleSnapshotIdentityMode; previousKeys?: ReadonlySet<string> };
}): Promise<{
  snapshot: string;
  truncated?: boolean;
  refs: Record<string, { role: string; name?: string; nth?: number }>;
  stats: { lines: number; chars: number; refs: number; interactive: number };
  newElements?: number;
}> {
  const page = await prepareSnapshotPageViaPlaywright({
    cdpUrl: opts.cdpUrl,
    targetId: opts.targetId,
    ssrfPolicy: opts.ssrfPolicy,
  });

  const ariaSnapshotTimeout = resolveSnapshotTimeoutMs(opts.timeoutMs);

  if (opts.refsMode === "aria") {
    if (normalizeOptionalString(opts.selector) || normalizeOptionalString(opts.frameSelector)) {
      throw new Error("refs=aria does not support selector/frame snapshots yet.");
    }
    return await withSnapshotFrameGuard({
      page,
      run: async (isFrameCurrent) => {
        const snapshot = await page.ariaSnapshot({
          mode: "ai",
          timeout: ariaSnapshotTimeout,
        });
        const built = buildRoleSnapshotFromAiSnapshot(snapshot, opts.options);
        return await finalizeRoleSnapshotViaPlaywright({
          page,
          cdpUrl: opts.cdpUrl,
          targetId: opts.targetId,
          isFrameCurrent,
          built,
          mode: "aria",
          urls: opts.urls,
          maxChars: opts.maxChars,

View on GitHub (pinned to 01804a7531)

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.

Example fix

// before
await snapshotViaPlaywright({
  cdpUrl, targetId,
  refsMode: "aria",
  selector: "#content",
});
// after — use role refs for selector-scoped snapshots
await snapshotViaPlaywright({
  cdpUrl, targetId,
  refsMode: "role",
  selector: "#content",
});

Defensive patterns

Strategy: validation

Validate before calling

function validateSnapshotOpts(opts: { refsMode?: string; selector?: string; frameSelector?: string }): void {
  if (opts.refsMode === "aria") {
    if ((opts.selector ?? "").trim() || (opts.frameSelector ?? "").trim()) {
      throw new Error("refsMode=aria cannot be combined with selector or frameSelector; use refsMode=role instead");
    }
  }
}

Prevention

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.

When it happens

Trigger: Calling snapshotViaPlaywright with opts.refsMode='aria' and a non-empty opts.selector or opts.frameSelector.

Common situations: 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.

Related errors

AI-assisted analysis of openclaw/openclaw@01804a7531 (2026-08-12). Data as JSON: /api/errors/b64d908943a1a792. Report an issue: GitHub.