What causes "${label} failed: ${error?.message ?? error}" in jackwener/OpenCLI?

Read the original message after 'failed:' — it names the root cause (timeout, DNS, blocked).

jackwener/OpenCLI · error · CommandExecutionError

${label} failed: ${error?.message ?? error}

Error message

${label} failed: ${error?.message ?? error}

What it means

runBrowserStep wraps an async browser step (page.goto, page.evaluate, etc.) and converts any thrown error into a CommandExecutionError labeled '<label> failed: <original message>'. Errors that already look like library errors (having a code, or being an ArgumentError by name) are re-thrown unchanged. So this message means the underlying browser automation step failed for a non-library reason.

Source

Thrown at clis/_shared/search-adapter.js:68

  try {
    const url = new URL(raw, baseUrl);
    if (url.protocol !== 'http:' && url.protocol !== 'https:') return '';
    return url.href;
  } catch {
    return '';
  }
}

export function emptySearchResults(site, query) {
  return new EmptyResultError(`${site} search`, `No ${site} results matched "${query}".`);
}

export async function runBrowserStep(label, fn) {
  try {
    return await fn();
  } catch (error) {
    if (error?.code || error?.name === 'ArgumentError') throw error;
    throw new CommandExecutionError(`${label} failed: ${error?.message ?? error}`);
  }
}

View on GitHub (pinned to 49907e53dc)

Solutions

Read the original message after 'failed:' — it names the root cause (timeout, DNS, blocked).
Retry the command; transient network/captcha failures often resolve.
Check connectivity/proxy settings and whether the site blocks headless browsers.
Increase any timeout options or re-run in foreground/non-headless mode; keep the browser session alive via the site's login command if auth-gated.

Defensive patterns

Strategy: try-catch

Validate before calling

// pre-check connectivity/site reachability
const res = await fetch(siteUrl, { method: 'HEAD' }).catch(() => null);
if (!res || !res.ok) console.warn('Site may be unreachable or blocked');

Try / catch

try {
  await runSearchCommand();
} catch (e) {
  if (e instanceof CommandExecutionError && e.message.includes('failed:')) {
    const cause = e.message.split('failed:')[1]?.trim();
    console.error(`Browser step failed: ${cause}; retrying may help`);
  } else throw e;
}

Prevention

Retry transient failures (timeouts, DNS) with backoff
Check network/proxy and whether the site blocks headless browsers
Read the root cause embedded after 'failed:' before changing code
Run auth/login commands first for gated sites

When it happens

Trigger: Any rejection inside the wrapped fn: navigation timeout, net::ERR_NAME_NOT_RESOLVED, page closed/crashed, or a JS exception inside page.evaluate — as long as the error lacks a .code and is not an ArgumentError.

Common situations: Site is down or blocking (403/captcha), DNS/proxy misconfiguration, headless browser crashes on heavy pages, navigation timeouts on slow networks, evaluate script throwing a TypeError in page context.

Related errors

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