{"record":{"id":"b354f75d7594a2e2","repo":"vercel-labs/agent-browser","slug":"agent-browser-args-0-failed-envelope","errorCode":null,"errorMessage":"agent-browser ${args[0] ?? \"\"} failed: ${envelope.error ?? \"unknown error\"}","messagePattern":"agent-browser (.+?) failed: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/@agent-browser/eve/extension/lib/browser.ts","lineNumber":86,"sourceCode":"  const config = extension.config;\n  const command = buildAgentBrowserCommand([...args, ...configArgs()], {\n    binary: config.binary,\n    session: config.session ?? defaultSessionName(config.sessionPrefix, sandbox.id),\n  });\n  const raw = await withDeadline(\n    sandbox.run({ abortSignal: ctx.abortSignal, command }),\n    \"The browser command\",\n  );\n  const result = createAgentBrowserCommandResult<CommandEnvelope<TData>>({\n    command,\n    exitCode: raw.exitCode,\n    stderr: raw.stderr,\n    stdout: raw.stdout,\n  });\n\n  const envelope = result.json;\n  if (envelope !== null && envelope.success === false) {\n    throw new Error(`agent-browser ${args[0] ?? \"\"} failed: ${envelope.error ?? \"unknown error\"}`);\n  }\n  if (result.exitCode !== 0) {\n    throw new AgentBrowserCommandError(result);\n  }\n  return (envelope?.data ?? null) as TData;\n}\n\nasync function requireSandbox(ctx: BrowserToolContext): Promise<EveSandboxSession> {\n  const sandbox = await withDeadline(ctx.getSandbox(), \"The sandbox session\");\n  if (sandbox === null || sandbox === undefined) {\n    throw new Error(\n      \"The browser tools require an eve sandbox. Configure agent/sandbox.ts in the consuming agent.\",\n    );\n  }\n  return sandbox;\n}\n\nasync function ensureInstalled(sandbox: EveSandboxSession, abortSignal?: AbortSignal): Promise<void> {","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/vercel-labs/agent-browser/blob/548b159b30eef119ccf6846c8bc807d0eaa3f6f8/packages/@agent-browser/eve/extension/lib/browser.ts#L68-L104","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the envelope.error text in the thrown message — it names the concrete CLI failure","Re-take a snapshot and use fresh refs/selectors, then retry the action","If the error mentions the session/browser, verify with 'agent-browser status' and relaunch"],"exampleFix":"// before: ref from an old snapshot\nawait tools.find({ by: \"ref\", query: \"@e12\", action: \"click\" }); // agent-browser find failed: ...\n\n// after: refresh then act\nawait tools.snapshot();\nawait tools.find({ by: \"ref\", query: \"@e3\", action: \"click\" });","handlingStrategy":"try-catch","validationCode":"// Refresh state before acting on refs:\n// const snap = await tools.snapshot();\n// assert the ref you plan to use exists in snap before find/get/click.","typeGuard":"function isEnvelopeFailure(error: unknown, command?: string): boolean {\n  return error instanceof Error\n    && error.message.startsWith(\"agent-browser \")\n    && error.message.includes(\" failed: \")\n    && (command === undefined || error.message.includes(`agent-browser ${command} failed:`));\n}","tryCatchPattern":"try {\n  return await runBrowser(ctx, args);\n} catch (error) {\n  if (error instanceof Error && error.message.includes(\" failed: \")) {\n    // envelope.error text follows the colon: element not found, bad selector, ...\n    // recover by re-snapshotting and retrying with fresh selectors\n  }\n  throw error;\n}","preventionTips":["Snapshot before every interaction batch and use fresh @refs","Prefer snapshot refs over hand-written CSS selectors","Treat envelope errors as recoverable domain failures, not crashes"],"tags":["eve","cli","selector","stale-state","envelope"],"backgroundTag":null,"analyzedSha":"548b159b30eef119ccf6846c8bc807d0eaa3f6f8","analyzedAt":"2026-08-16T10:12:14.925Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}