vercel-labs/agent-browser · error

@vercel/sandbox did not export Sandbox.

Error message

@vercel/sandbox did not export Sandbox.

What it means

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.

Source

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

    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 ?? {};
}

function formatDnfPackageName(name: string): string {
  if (!SAFE_DNF_PACKAGE_NAME.test(name)) {
    throw new Error(`Invalid system dependency name: ${JSON.stringify(name)}`);
  }
  return quoteShellArg(name);
}

View on GitHub (pinned to 548b159b30)

Solutions

  1. Upgrade @vercel/sandbox to a current version compatible with @agent-browser/sandbox (`pnpm update @vercel/sandbox` or pin the latest in package.json).
  2. 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.
  3. 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.
  4. 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.

Example fix

// before
await withAgentBrowserSandbox(fn); // throws: did not export Sandbox

// after
import { Sandbox } from "@vercel/sandbox";
await withAgentBrowserSandbox(fn, { Sandbox });
Defensive patterns

Strategy: type-guard

Validate before calling

// Verify the export shape before relying on the provider
import * as mod from "@vercel/sandbox";

if (typeof (mod as Record<string, unknown>).Sandbox !== "function") {
  throw new Error(
    "Incompatible @vercel/sandbox version: expected a Sandbox export. Upgrade with pnpm update @vercel/sandbox.",
  );
}

Type guard

function isSandboxExport(mod: unknown): mod is { Sandbox: unknown } {
  return (
    typeof mod === "object" &&
    mod !== null &&
    "Sandbox" in mod &&
    (typeof (mod as { Sandbox: unknown }).Sandbox === "function" ||
      typeof (mod as { Sandbox: unknown }).Sandbox === "object")
  );
}

const mod: unknown = await import("@vercel/sandbox");
if (isSandboxExport(mod)) {
  await withAgentBrowserSandbox(fn, { Sandbox: mod.Sandbox as never });
}

Try / catch

try {
  await withAgentBrowserSandbox(fn);
} catch (error) {
  if (error instanceof Error && error.message.includes("did not export Sandbox")) {
    // version/export-shape mismatch: upgrade the SDK or inject the constructor; retrying unchanged will not help
    throw new Error("@vercel/sandbox version mismatch. Run: pnpm update @vercel/sandbox");
  }
  throw error;
}

Prevention

When it happens

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

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

Related errors

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