@agent-browser/sandbox/vercel requires @vercel/sandbox. Inst

Error message

@agent-browser/sandbox/vercel requires @vercel/sandbox. Install it in your app to use this provider. ${String(error)}

What it means

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.

Source

Thrown at packages/@agent-browser/sandbox/src/vercel.ts:331

  step: string,
  fn: () => Promise<T>,
  onStep: SandboxStepHandler | undefined,
): Promise<T> {
  const start = Date.now();
  onStep?.({ status: "running", step });
  try {
    const result = await fn();
    onStep?.({ elapsed: Date.now() - start, status: "done", step });
    return result;
  } catch (error) {
    onStep?.({ elapsed: Date.now() - start, status: "error", step });
    throw error;
  }
}

async function loadVercelSandboxConstructor(): Promise<VercelSandboxConstructor> {
  const mod = (await import("@vercel/sandbox").catch((error: unknown) => {
    throw new Error(
      `@agent-browser/sandbox/vercel requires @vercel/sandbox. Install it in your app to use this provider. ${String(
        error,
      )}`,
    );
  })) as Record<string, unknown>;
  const Sandbox = mod.Sandbox;
  if (typeof Sandbox !== "function" && typeof Sandbox !== "object") {
    throw new Error("@vercel/sandbox did not export Sandbox.");
  }
  return Sandbox as VercelSandboxConstructor;
}

function defaultEnv(): Readonly<Record<string, string | undefined>> {
  const globalWithProcess = globalThis as typeof globalThis & {
    readonly process?: { readonly env?: Readonly<Record<string, string | undefined>> };
  };
  return globalWithProcess.process?.env ?? {};
}

View on GitHub (pinned to 548b159b30)

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.

Example fix

// before
const result = await withAgentBrowserSandbox(async (sandbox) => {
  await runAgentBrowserCommand(sandbox, ["open", url]);
});

// after (option A: install the peer dep)
// pnpm add @vercel/sandbox

// after (option B: inject the constructor explicitly)
import { Sandbox } from "@vercel/sandbox";
const result = await withAgentBrowserSandbox(
  async (sandbox) => {
    await runAgentBrowserCommand(sandbox, ["open", url]);
  },
  { Sandbox },
);

Defensive patterns

Strategy: validation

Validate before calling

// Run once at startup, before any sandbox call
async function assertVercelSandboxAvailable(): Promise<void> {
  try {
    const mod = (await import("@vercel/sandbox")) as { Sandbox?: unknown };
    if (typeof mod.Sandbox !== "function" && typeof mod.Sandbox !== "object") {
      throw new Error("@vercel/sandbox resolved but has no Sandbox export");
    }
  } catch {
    throw new Error("Run `pnpm add @vercel/sandbox` to use the Vercel sandbox provider");
  }
}

Type guard

import type { Sandbox as VercelSandbox } from "@vercel/sandbox";

function isSandboxConstructor(value: unknown): value is typeof VercelSandbox {
  return typeof value === "function" || typeof value === "object";
}

Try / catch

try {
  result = await withAgentBrowserSandbox(fn);
} catch (error) {
  if (error instanceof Error && error.message.includes("requires @vercel/sandbox")) {
    // fail fast with an actionable setup error; do not retry
    throw new Error("Setup missing: pnpm add @vercel/sandbox (original: " + error.message + ")");
  }
  throw error;
}

Prevention

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.

When it happens

Trigger: 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).

Common situations: 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.

Related errors

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