What causes "browser hover is not supported by this browser backend" in jackwener/OpenCLI?

Use a browser backend that supports mouse interaction (Playwright/Puppeteer-based).

browser hover is not supported by this browser backend

Error message

browser hover is not supported by this browser backend

What it means

The `browser hover` command checks that the active page backend implements a `hover` method before proceeding. Backends that only implement a minimal page interface (e.g. raw CDP or DOM-less drivers) do not support hovering, so the command fails fast with this capability error instead of an undefined-function crash.

Source

Thrown at src/cli.ts:2107

      if (isAutocomplete) await page.wait(0.4);
      console.log(JSON.stringify({
        typed: true,
        text: resolved.value,
        target: resolved.target,
        matches_n,
        match_level,
        autocomplete: !!isAutocomplete,
      }, null, 2));
    }));

  addBrowserTabOption(
    addSemanticLocatorOptions(browser.command('hover'))
      .argument('[target]', 'Numeric ref (from browser state / find), CSS selector, or omit when using --role/--name/etc.')
      .option('--nth <n>', 'When <target> is a multi-match CSS selector, pick the nth match (0-based)')
      .description('Move the mouse over an element — JSON envelope {hovered, target, matches_n}'),
  )
    .action(browserAction(async (page, target, opts) => {
      if (typeof page.hover !== 'function') throw new Error('browser hover is not supported by this browser backend');
      const resolvedTarget = await resolveWriteTargetOrPrint(page, target, opts ?? {});
      if (!resolvedTarget) return;
      const parsed = nthToResolveOpts(opts?.nth);
      if ('error' in parsed) {
        console.log(JSON.stringify({ error: { code: 'usage_error', message: parsed.error } }, null, 2));
        process.exitCode = EXIT_CODES.USAGE_ERROR;
        return;
      }
      const { matches_n, match_level } = await page.hover(resolvedTarget, parsed.opts);
      console.log(JSON.stringify({ hovered: true, target: resolvedTarget, matches_n, match_level }, null, 2));
    }));

  addBrowserTabOption(
    addSemanticLocatorOptions(browser.command('focus'))
      .argument('[target]', 'Numeric ref (from browser state / find), CSS selector, or omit when using --role/--name/etc.')
      .option('--nth <n>', 'When <target> is a multi-match CSS selector, pick the nth match (0-based)')
      .description('Focus an element — JSON envelope {focused, target, matches_n}'),
  )

View on GitHub (pinned to 49907e53dc)

Solutions

Use a browser backend that supports mouse interaction (Playwright/Puppeteer-based).
Emulate hover another way, e.g. `browser eval` dispatching mouseover/mouseenter events.
Check the backend configuration (driver/browser flag) and switch to a full-featured one.

Example fix

// before
browser --backend minimal hover 'button.submit'
// after
browser --backend playwright hover 'button.submit'

Defensive patterns

Strategy: type-guard

Validate before calling

const page = await getBrowserPage();
if (typeof page.hover !== 'function') {
  throw new Error('Current backend cannot hover; use --backend playwright');
}

Type guard

function supportsHover(page) {
  return typeof page?.hover === 'function';
}

Try / catch

try {
  await run(['browser', 'hover', sel]);
} catch (err) {
  if (String(err.message).includes('hover is not supported')) {
    await run(['browser', 'eval', `document.querySelector('${sel}').dispatchEvent(new MouseEvent('mouseover', {bubbles:true}))`]);
  } else throw err;
}

Prevention

Feature-check page.hover before issuing hover commands.
Pin browser backend config to one that implements mouse APIs.
Document which commands your chosen backend supports.
Wrap capability-dependent commands in a compatibility helper.

When it happens

Trigger: Running `browser hover [target]` while connected to a browser backend whose page object lacks `page.hover` (feature-detection via `typeof page.hover !== 'function'`).

Common situations: Using a non-Playwright/Puppeteer backend, a headless custom driver, or an older/limited backend adapter; switching browser backend config so hover is unavailable in the new environment.

Related errors

AI-assisted analysis of jackwener/OpenCLI@49907e53dc (2026-08-29). Data as JSON: /api/errors/f916439a1e275b9c. Report an issue: GitHub.