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

throwIfCommandFailed in @agent-browser/sandbox checks result.exitCode and throws AgentBrowserCommandError on any non-zero exit. The message is 'agent-browser command failed: <command>\n<detail>' with detail taken from trimmed stderr, else trimmed stdout, else 'exit N'. The error object also carries command, exitCode, stderr and stdout for programmatic handling. This is the generic failure path used by runAgentBrowser when the CLI did not produce a success envelope.

Source

Thrown at packages/@agent-browser/sandbox/src/shared.ts:116

  readonly exitCode?: number;
  readonly stderr?: string;
  readonly stdout?: string;
}): AgentBrowserCommandResult<TJson> {
  const stdout = input.stdout ?? "";
  return {
    command: input.command,
    exitCode: input.exitCode ?? 0,
    json: parseJson<TJson>(stdout),
    stderr: input.stderr ?? "",
    stdout,
  };
}

export function throwIfCommandFailed<TJson>(
  result: AgentBrowserCommandResult<TJson>,
): AgentBrowserCommandResult<TJson> {
  if (result.exitCode !== 0) {
    throw new AgentBrowserCommandError(result);
  }
  return result;
}

export function defaultSessionName(prefix: string, id: string): string {
  const safePrefix = sanitizeSessionPart(prefix) || "agent-browser";
  const safeId = sanitizeSessionPart(id) || "default";
  return truncateSessionName(`${safePrefix}-${safeId}`);
}

function formatShellEnv(env: Readonly<Record<string, string | undefined>> | undefined): string {
  if (env === undefined) return "";
  return Object.entries(env)
    .filter((entry): entry is [string, string] => entry[1] !== undefined)
    .map(([key, value]) => {
      if (!SAFE_ENV_KEY.test(key)) {
        throw new Error(`Invalid environment variable name: ${key}`);
      }

View on GitHub (pinned to 548b159b30)

Solutions

1. Catch AgentBrowserCommandError and read .stderr / .stdout / .exitCode to classify the failure
2. Fix the underlying command per the stderr text (selector, flag, session), then retry
3. Keep the installed agent-browser version in sync with @agent-browser/sandbox's AGENT_BROWSER_SANDBOX_VERSION

Example fix

// before
const result = await runAgentBrowser(ctx, ["tab"]);
throwIfCommandFailed(result); // throws on exit 1

// after
try {
  throwIfCommandFailed(result);
} catch (error) {
  if (error instanceof AgentBrowserCommandError) {
    console.error(error.command, error.exitCode, error.stderr);
  }
}

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

try {
  return throwIfCommandFailed(result);
} catch (error) {
  if (error instanceof AgentBrowserCommandError) {
    // classify: error.exitCode, error.stderr, error.stdout, error.command
    // retry only for transient causes (daemon starting); surface the rest
  }
  throw error;
}

When it happens

Trigger: Calling runAgentBrowser for a command that exits non-zero: unknown subcommand/flag, session errors, element-not-found without --json envelope, missing binary, or the agent-browser daemon not running.

Common situations: Version skew between the installed CLI and the args the helper builds; daemon stopped or crashed; invalid selectors or state-dependent failures surfacing as exit codes.

Related errors

• agent-browser command failed: ${result.command}\n${detail}
• React DevTools hook not installed - relaunch with --enable r
• renders recording not active - run `react renders start` fir
• agent-browser ${args[0] ?? ""} failed: ${envelope.error ?? "
• Screenshot did not return a file path.

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