vercel-labs/agent-browser · error · AgentBrowserCommandError

agent-browser command failed: ${result.command}\n${detail}

Error message

agent-browser command failed: ${result.command}\n${detail}

What it means

In eve's runBrowser, after the JSON-envelope check, a non-zero exit code throws AgentBrowserCommandError. This path means the CLI process itself failed without a parseable failure envelope: binary missing or not installed, crashes, usage errors, or garbage on stdout. The message is 'agent-browser command failed: <command>\n<detail>' where detail is trimmed stderr (or stdout, or 'exit N').

Source

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

    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> {
  if (!extension.config.autoInstall) {
    return;
  }

View on GitHub (pinned to 548b159b30)

Solutions

  1. Inspect error.stderr/error.command on the thrown AgentBrowserCommandError to see the exact failing command and stderr
  2. Ensure the binary exists in the sandbox: run 'command -v agent-browser'; if missing, enable extension autoInstall or install the matching 'agent-browser@<version>' spec
  3. Align the installed CLI version with the eve extension's expected version (AGENT_BROWSER_SANDBOX_VERSION)

Example fix

// before
const ext = configure({ autoInstall: false });   // binary missing -> exit 127

// after
import { AGENT_BROWSER_SANDBOX_VERSION } from "@agent-browser/sandbox";
const ext = configure({ autoInstall: true, installSpec: `agent-browser@${AGENT_BROWSER_SANDBOX_VERSION}` });
Defensive patterns

Strategy: try-catch

Validate before calling

// Before running tools, verify the binary in the sandbox:
// const probe = await sandbox.run({ command: "command -v agent-browser" });
// if (probe.exitCode !== 0) install before proceeding.

Type guard

import { AgentBrowserCommandError } from "@agent-browser/sandbox";
function isCommandError(error: unknown): error is AgentBrowserCommandError {
  return error instanceof AgentBrowserCommandError;
}

Try / catch

try {
  return await runBrowser(ctx, args);
} catch (error) {
  if (error instanceof AgentBrowserCommandError) {
    logger.error({ command: error.command, exitCode: error.exitCode, stderr: error.stderr });
    // exit 127 => binary missing; 1 with usage text => version skew
  }
  throw error;
}

Prevention

When it happens

Trigger: agent-browser binary absent from PATH in the sandbox and autoInstall disabled or failed; CLI version mismatch (unknown flags); native binary crash; sandbox.run returning a non-zero exit for environment reasons.

Common situations: Fresh sandboxes where installation raced or config.autoInstall was turned off; pinned old CLI versions that lack newer flags the extension passes; restricted sandboxes without network for install.

Related errors

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