{"record":{"id":"fa841e64e38aff18","repo":"vercel-labs/agent-browser","slug":"agent-browser-command-failed-result-command-n-fa841e","errorCode":null,"errorMessage":"agent-browser command failed: ${result.command}\\n${detail}","messagePattern":"agent-browser command failed: (.+?)\\\\n(.+?)","errorType":"exception","errorClass":"AgentBrowserCommandError","httpStatus":null,"severity":"error","filePath":"packages/@agent-browser/sandbox/src/shared.ts","lineNumber":116,"sourceCode":"  readonly exitCode?: number;\n  readonly stderr?: string;\n  readonly stdout?: string;\n}): AgentBrowserCommandResult<TJson> {\n  const stdout = input.stdout ?? \"\";\n  return {\n    command: input.command,\n    exitCode: input.exitCode ?? 0,\n    json: parseJson<TJson>(stdout),\n    stderr: input.stderr ?? \"\",\n    stdout,\n  };\n}\n\nexport function throwIfCommandFailed<TJson>(\n  result: AgentBrowserCommandResult<TJson>,\n): AgentBrowserCommandResult<TJson> {\n  if (result.exitCode !== 0) {\n    throw new AgentBrowserCommandError(result);\n  }\n  return result;\n}\n\nexport function defaultSessionName(prefix: string, id: string): string {\n  const safePrefix = sanitizeSessionPart(prefix) || \"agent-browser\";\n  const safeId = sanitizeSessionPart(id) || \"default\";\n  return truncateSessionName(`${safePrefix}-${safeId}`);\n}\n\nfunction formatShellEnv(env: Readonly<Record<string, string | undefined>> | undefined): string {\n  if (env === undefined) return \"\";\n  return Object.entries(env)\n    .filter((entry): entry is [string, string] => entry[1] !== undefined)\n    .map(([key, value]) => {\n      if (!SAFE_ENV_KEY.test(key)) {\n        throw new Error(`Invalid environment variable name: ${key}`);\n      }","sourceCodeStart":98,"sourceCodeEnd":134,"githubUrl":"https://github.com/vercel-labs/agent-browser/blob/548b159b30eef119ccf6846c8bc807d0eaa3f6f8/packages/@agent-browser/sandbox/src/shared.ts#L98-L134","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Catch AgentBrowserCommandError and read .stderr / .stdout / .exitCode to classify the failure","Fix the underlying command per the stderr text (selector, flag, session), then retry","Keep the installed agent-browser version in sync with @agent-browser/sandbox's AGENT_BROWSER_SANDBOX_VERSION"],"exampleFix":"// before\nconst result = await runAgentBrowser(ctx, [\"tab\"]);\nthrowIfCommandFailed(result); // throws on exit 1\n\n// after\ntry {\n  throwIfCommandFailed(result);\n} catch (error) {\n  if (error instanceof AgentBrowserCommandError) {\n    console.error(error.command, error.exitCode, error.stderr);\n  }\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"import { AgentBrowserCommandError } from \"@agent-browser/sandbox\";\nfunction isCommandError(error: unknown): error is AgentBrowserCommandError {\n  return error instanceof AgentBrowserCommandError;\n}","tryCatchPattern":"try {\n  return throwIfCommandFailed(result);\n} catch (error) {\n  if (error instanceof AgentBrowserCommandError) {\n    // classify: error.exitCode, error.stderr, error.stdout, error.command\n    // retry only for transient causes (daemon starting); surface the rest\n  }\n  throw error;\n}","preventionTips":["Always narrow with 'instanceof AgentBrowserCommandError' before reading stderr/exitCode","Log error.command to reproduce failures manually in the sandbox shell","Keep the CLI version aligned with @agent-browser/sandbox to avoid usage-error exit codes"],"tags":["cli","process-exit","error-handling","sandbox-package"],"backgroundTag":null,"analyzedSha":"548b159b30eef119ccf6846c8bc807d0eaa3f6f8","analyzedAt":"2026-08-16T10:12:14.925Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}