vercel-labs/agent-browser · error

agent-browser ${args[0] ?? ""} failed: ${envelope.error ?? "

Error message

agent-browser ${args[0] ?? ""} failed: ${envelope.error ?? "unknown error"}

What it means

runBrowser in the eve extension executes the agent-browser CLI with --json and parses an envelope {success, data, error}. success:false means the command ran and reported a domain-level failure in envelope.error — the structured error text the CLI produces for things like 'no element matches selector' or navigation failures. The thrown Error prefixes the failing subcommand name and appends envelope.error.

Source

Thrown at packages/@agent-browser/eve/extension/lib/browser.ts:86

  const config = extension.config;
  const command = buildAgentBrowserCommand([...args, ...configArgs()], {
    binary: config.binary,
    session: config.session ?? defaultSessionName(config.sessionPrefix, sandbox.id),
  });
  const raw = await withDeadline(
    sandbox.run({ abortSignal: ctx.abortSignal, command }),
    "The browser command",
  );
  const result = createAgentBrowserCommandResult<CommandEnvelope<TData>>({
    command,
    exitCode: raw.exitCode,
    stderr: raw.stderr,
    stdout: raw.stdout,
  });

  const envelope = result.json;
  if (envelope !== null && envelope.success === false) {
    throw new Error(`agent-browser ${args[0] ?? ""} failed: ${envelope.error ?? "unknown error"}`);
  }
  if (result.exitCode !== 0) {
    throw new AgentBrowserCommandError(result);
  }
  return (envelope?.data ?? null) as TData;
}

async function requireSandbox(ctx: BrowserToolContext): Promise<EveSandboxSession> {
  const sandbox = await withDeadline(ctx.getSandbox(), "The sandbox session");
  if (sandbox === null || sandbox === undefined) {
    throw new Error(
      "The browser tools require an eve sandbox. Configure agent/sandbox.ts in the consuming agent.",
    );
  }
  return sandbox;
}

async function ensureInstalled(sandbox: EveSandboxSession, abortSignal?: AbortSignal): Promise<void> {

View on GitHub (pinned to 548b159b30)

Solutions

1. Read the envelope.error text in the thrown message — it names the concrete CLI failure
2. Re-take a snapshot and use fresh refs/selectors, then retry the action
3. If the error mentions the session/browser, verify with 'agent-browser status' and relaunch

Example fix

// before: ref from an old snapshot
await tools.find({ by: "ref", query: "@e12", action: "click" }); // agent-browser find failed: ...

// after: refresh then act
await tools.snapshot();
await tools.find({ by: "ref", query: "@e3", action: "click" });

// Refresh state before acting on refs:
// const snap = await tools.snapshot();
// assert the ref you plan to use exists in snap before find/get/click.

function isEnvelopeFailure(error: unknown, command?: string): boolean {
  return error instanceof Error
    && error.message.startsWith("agent-browser ")
    && error.message.includes(" failed: ")
    && (command === undefined || error.message.includes(`agent-browser ${command} failed:`));
}

try {
  return await runBrowser(ctx, args);
} catch (error) {
  if (error instanceof Error && error.message.includes(" failed: ")) {
    // envelope.error text follows the colon: element not found, bad selector, ...
    // recover by re-snapshotting and retrying with fresh selectors
  }
  throw error;
}

When it happens

Trigger: Any eve browser tool call where the CLI returns a structured failure: acting on a snapshot ref like @e12 that no longer exists, invalid CSS/text/xpath selectors, open of an unreachable URL, actions against a closed or crashed session.

Common situations: Agents using refs from a stale snapshot after the page changed; typos in selectors; the page navigated between snapshot and action; daemon/session lifecycle races.

Related errors

• agent-browser command failed: ${result.command}\n${detail}
• The "${property}" property requires a selector.
• React DevTools hook not installed - relaunch with --enable r
• No React renderer attached
• inspect failed: ${result && result.type}

AI-assisted analysis of vercel-labs/agent-browser@548b159b30 (2026-08-16). Data as JSON: /api/errors/b354f75d7594a2e2. Report an issue: GitHub.