{"record":{"id":"bcfbd1d3e2516cad","repo":"vercel-labs/agent-browser","slug":"agent-browser-sandbox-vercel-requires-vercel-san","errorCode":null,"errorMessage":"@agent-browser/sandbox/vercel requires @vercel/sandbox. Install it in your app to use this provider. ${String(error)}","messagePattern":"@agent-browser/sandbox/vercel requires @vercel/sandbox\\. Install it in your app to use this provider\\. (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"packages/@agent-browser/sandbox/src/vercel.ts","lineNumber":331,"sourceCode":"  step: string,\n  fn: () => Promise<T>,\n  onStep: SandboxStepHandler | undefined,\n): Promise<T> {\n  const start = Date.now();\n  onStep?.({ status: \"running\", step });\n  try {\n    const result = await fn();\n    onStep?.({ elapsed: Date.now() - start, status: \"done\", step });\n    return result;\n  } catch (error) {\n    onStep?.({ elapsed: Date.now() - start, status: \"error\", step });\n    throw error;\n  }\n}\n\nasync function loadVercelSandboxConstructor(): Promise<VercelSandboxConstructor> {\n  const mod = (await import(\"@vercel/sandbox\").catch((error: unknown) => {\n    throw new Error(\n      `@agent-browser/sandbox/vercel requires @vercel/sandbox. Install it in your app to use this provider. ${String(\n        error,\n      )}`,\n    );\n  })) as Record<string, unknown>;\n  const Sandbox = mod.Sandbox;\n  if (typeof Sandbox !== \"function\" && typeof Sandbox !== \"object\") {\n    throw new Error(\"@vercel/sandbox did not export Sandbox.\");\n  }\n  return Sandbox as VercelSandboxConstructor;\n}\n\nfunction defaultEnv(): Readonly<Record<string, string | undefined>> {\n  const globalWithProcess = globalThis as typeof globalThis & {\n    readonly process?: { readonly env?: Readonly<Record<string, string | undefined>> };\n  };\n  return globalWithProcess.process?.env ?? {};\n}","sourceCodeStart":313,"sourceCodeEnd":349,"githubUrl":"https://github.com/vercel-labs/agent-browser/blob/548b159b30eef119ccf6846c8bc807d0eaa3f6f8/packages/@agent-browser/sandbox/src/vercel.ts#L313-L349","documentation":"The Vercel provider lazy-loads its peer dependency via `await import(\"@vercel/sandbox\")` inside loadVercelSandboxConstructor (vercel.ts:329-345). If the dynamic import rejects, the rejection is rethrown with install instructions plus the original error text. This fires when withAgentBrowserSandbox or createAgentBrowserSnapshot is called without an explicit options.Sandbox constructor and @vercel/sandbox cannot be resolved in the host app.","triggerScenarios":"Calling withAgentBrowserSandbox(fn) or createAgentBrowserSnapshot(...) (vercel.ts:169 and vercel.ts:252 fall back to loadVercelSandboxConstructor) in a project where @vercel/sandbox is not in package.json, is not bundled into the serverless output, or fails to resolve in an ESM/CJS mixed runtime. The wrapped String(error) preserves the underlying cause (e.g. ERR_MODULE_NOT_FOUND).","commonSituations":"Installing only @agent-browser/sandbox and assuming the Vercel SDK ships with it (it is a peer dependency); Next.js/Nuxt serverless bundling that tree-shakes or never includes the optional import path; pnpm strict node_modules isolation in monorepos where the dep is declared in a sibling package; CI running a different install than production.","solutions":["Install the peer dependency in the app: `pnpm add @vercel/sandbox` (or npm/yarn equivalent), then retry.","If you already have the SDK but resolution fails in your bundler, import { Sandbox } from \"@vercel/sandbox\" yourself and pass it as options.Sandbox to withAgentBrowserSandbox/createAgentBrowserSnapshot, bypassing the dynamic import.","Check the trailing original error in the message (module not found vs syntax error vs permissions) to distinguish a missing package from a broken install; run `npm ls @vercel/sandbox` or reinstall node_modules.","For monorepos, declare @vercel/sandbox in the package that actually calls the Vercel provider so the bundler can resolve it from that package's node_modules."],"exampleFix":"// before\nconst result = await withAgentBrowserSandbox(async (sandbox) => {\n  await runAgentBrowserCommand(sandbox, [\"open\", url]);\n});\n\n// after (option A: install the peer dep)\n// pnpm add @vercel/sandbox\n\n// after (option B: inject the constructor explicitly)\nimport { Sandbox } from \"@vercel/sandbox\";\nconst result = await withAgentBrowserSandbox(\n  async (sandbox) => {\n    await runAgentBrowserCommand(sandbox, [\"open\", url]);\n  },\n  { Sandbox },\n);","handlingStrategy":"validation","validationCode":"// Run once at startup, before any sandbox call\nasync function assertVercelSandboxAvailable(): Promise<void> {\n  try {\n    const mod = (await import(\"@vercel/sandbox\")) as { Sandbox?: unknown };\n    if (typeof mod.Sandbox !== \"function\" && typeof mod.Sandbox !== \"object\") {\n      throw new Error(\"@vercel/sandbox resolved but has no Sandbox export\");\n    }\n  } catch {\n    throw new Error(\"Run `pnpm add @vercel/sandbox` to use the Vercel sandbox provider\");\n  }\n}","typeGuard":"import type { Sandbox as VercelSandbox } from \"@vercel/sandbox\";\n\nfunction isSandboxConstructor(value: unknown): value is typeof VercelSandbox {\n  return typeof value === \"function\" || typeof value === \"object\";\n}","tryCatchPattern":"try {\n  result = await withAgentBrowserSandbox(fn);\n} catch (error) {\n  if (error instanceof Error && error.message.includes(\"requires @vercel/sandbox\")) {\n    // fail fast with an actionable setup error; do not retry\n    throw new Error(\"Setup missing: pnpm add @vercel/sandbox (original: \" + error.message + \")\");\n  }\n  throw error;\n}","preventionTips":["Declare @vercel/sandbox in the dependencies of the exact package that imports @agent-browser/sandbox/vercel, and commit the lockfile.","Add a CI smoke test that imports the Vercel provider entry point in the production bundler config so missing peer deps fail the build, not runtime.","If your bundler cannot resolve it, import { Sandbox } yourself and pass options.Sandbox so resolution is explicit.","Read the trailing String(error) in the message; ERR_MODULE_NOT_FOUND means missing install, other codes point to bundler/ESM issues."],"tags":["dependencies","vercel","sandbox","peer-dependency","install"],"backgroundTag":null,"analyzedSha":"548b159b30eef119ccf6846c8bc807d0eaa3f6f8","analyzedAt":"2026-08-16T10:12:14.925Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}