{"record":{"id":"d5dae4682cef1767","repo":"vercel-labs/agent-browser","slug":"vercel-sandbox-did-not-export-sandbox","errorCode":null,"errorMessage":"@vercel/sandbox did not export Sandbox.","messagePattern":"@vercel/sandbox did not export Sandbox\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/@agent-browser/sandbox/src/vercel.ts","lineNumber":339,"sourceCode":"    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}\n\nfunction formatDnfPackageName(name: string): string {\n  if (!SAFE_DNF_PACKAGE_NAME.test(name)) {\n    throw new Error(`Invalid system dependency name: ${JSON.stringify(name)}`);\n  }\n  return quoteShellArg(name);\n}\n","sourceCodeStart":321,"sourceCodeEnd":357,"githubUrl":"https://github.com/vercel-labs/agent-browser/blob/548b159b30eef119ccf6846c8bc807d0eaa3f6f8/packages/@agent-browser/sandbox/src/vercel.ts#L321-L357","documentation":"After the dynamic import of @vercel/sandbox succeeds, loadVercelSandboxConstructor reads `mod.Sandbox` and requires it to be a function or object (vercel.ts:336-339). If the module resolves but has no usable `Sandbox` binding, the provider cannot construct sandboxes and throws this error. It indicates a version/export-shape mismatch rather than a missing package.","triggerScenarios":"Calling withAgentBrowserSandbox or createAgentBrowserSnapshot without options.Sandbox while the resolved @vercel/sandbox version exports the class under a different name, as a default-export-only CJS module (Sandbox reachable only via mod.default.Sandbox), or as undefined. Also triggered by test doubles that mock the module without a Sandbox export.","commonSituations":"A much older or newer @vercel/sandbox release with a changed public API; bundler interop that wraps the CJS module so named exports land under `default`; a stale lockfile after a major-version bump of the SDK; jest/vi.mock replacing @vercel/sandbox with a partial fake.","solutions":["Upgrade @vercel/sandbox to a current version compatible with @agent-browser/sandbox (`pnpm update @vercel/sandbox` or pin the latest in package.json).","Sanity-check the export in isolation: `import * as m from \"@vercel/sandbox\"; console.log(typeof m.Sandbox);` in the same runtime/bundler config that fails.","If you must stay on a version with a different export shape, import Sandbox yourself and pass it via options.Sandbox to skip the constructor probing entirely.","For ESM/CJS interop, configure the bundler (e.g. Next.js transpilePackages or esbuild external) so @vercel/sandbox keeps its named exports instead of being nested under default."],"exampleFix":"// before\nawait withAgentBrowserSandbox(fn); // throws: did not export Sandbox\n\n// after\nimport { Sandbox } from \"@vercel/sandbox\";\nawait withAgentBrowserSandbox(fn, { Sandbox });","handlingStrategy":"type-guard","validationCode":"// Verify the export shape before relying on the provider\nimport * as mod from \"@vercel/sandbox\";\n\nif (typeof (mod as Record<string, unknown>).Sandbox !== \"function\") {\n  throw new Error(\n    \"Incompatible @vercel/sandbox version: expected a Sandbox export. Upgrade with pnpm update @vercel/sandbox.\",\n  );\n}","typeGuard":"function isSandboxExport(mod: unknown): mod is { Sandbox: unknown } {\n  return (\n    typeof mod === \"object\" &&\n    mod !== null &&\n    \"Sandbox\" in mod &&\n    (typeof (mod as { Sandbox: unknown }).Sandbox === \"function\" ||\n      typeof (mod as { Sandbox: unknown }).Sandbox === \"object\")\n  );\n}\n\nconst mod: unknown = await import(\"@vercel/sandbox\");\nif (isSandboxExport(mod)) {\n  await withAgentBrowserSandbox(fn, { Sandbox: mod.Sandbox as never });\n}","tryCatchPattern":"try {\n  await withAgentBrowserSandbox(fn);\n} catch (error) {\n  if (error instanceof Error && error.message.includes(\"did not export Sandbox\")) {\n    // version/export-shape mismatch: upgrade the SDK or inject the constructor; retrying unchanged will not help\n    throw new Error(\"@vercel/sandbox version mismatch. Run: pnpm update @vercel/sandbox\");\n  }\n  throw error;\n}","preventionTips":["Pin @vercel/sandbox to a known-good major version in package.json and upgrade it deliberately alongside @agent-browser/sandbox.","Pass options.Sandbox explicitly when you control the import; it removes the probing code path entirely.","Add a startup assertion on typeof (await import(\"@vercel/sandbox\")).Sandbox in health checks for serverless deployments.","Watch for ESM/CJS interop in bundled builds; check whether named exports got nested under module.default before suspecting the SDK."],"tags":["vercel","version-mismatch","exports","esm-cjs","sandbox"],"backgroundTag":null,"analyzedSha":"548b159b30eef119ccf6846c8bc807d0eaa3f6f8","analyzedAt":"2026-08-16T10:12:14.925Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}