The Open Framework for Building Agents
Clarify Vercel sandbox backend errors (#341)
JJ Kasper86ae773f5fd1
diff --git a/.changeset/vercel-local-backend-errors.md b/.changeset/vercel-local-backend-errors.mdnew file mode 100644index 000000000..141f20613--- /dev/null+++ b/.changeset/vercel-local-backend-errors.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Clarify Vercel build failures when an agent pins the Docker or microsandbox sandbox backend. The error now explains those local backends are unavailable on Vercel and directs users to `defaultBackend()` or an explicit Vercel-compatible backend.diff --git a/packages/eve/src/execution/sandbox/prewarm.test.ts b/packages/eve/src/execution/sandbox/prewarm.test.tsindex 368c9d0e1..6fb620ab2 100644--- a/packages/eve/src/execution/sandbox/prewarm.test.ts+++ b/packages/eve/src/execution/sandbox/prewarm.test.ts@@ -1,4 +1,4 @@-import { describe, expect, it, vi } from "vitest";+import { afterEach, describe, expect, it, vi } from "vitest";import { prewarmAppSandboxes } from "#execution/sandbox/prewarm.js";import type {@@ -16,6 +16,10 @@ vi.mock("#execution/sandbox/template-prewarm-lock.js", () => ({}));describe("prewarmAppSandboxes", () => {+ afterEach(() => {+ vi.unstubAllEnvs();+ });+it("uses the stable sandbox app root for dev snapshot artifact sources", async () => {const appRoot = process.cwd();const firstSnapshotRoot = `${appRoot}/.eve/dev-runtime/snapshots/one/app`;@@ -68,6 +72,46 @@ describe("prewarmAppSandboxes", () => {expect(inputs).toHaveLength(0);expect(signatures).toHaveLength(1);});++ it.each(["docker", "microsandbox"])(+ "explains that %s is unavailable during Vercel prewarm",+ async (backendName) => {+ vi.stubEnv("VERCEL", "1");++ const appRoot = process.cwd();+ const cause = new Error("backend host check failed");+ const log = vi.fn();++ await expect(+ prewarmAppSandboxes({+ appRoot,+ compiledArtifactsSource: createDiskRuntimeCompiledArtifactsSource(appRoot),+ dispatch: async () => {+ throw cause;+ },+ loadAgentGraph: async () => createGraph(backendName),+ log,+ }),+ ).rejects.toMatchObject({+ cause,+ message: expect.stringContaining(+ `The ${backendName} sandbox backend is not available when deploying on Vercel.`,+ ),+ });++ const messages = log.mock.calls.map(([message]) => String(message));+ expect(messages).toEqual([+ "eve: initializing 1 sandbox template...",+ expect.stringContaining(+ `The ${backendName} sandbox backend is not available when deploying on Vercel.`,+ ),+ ]);+ expect(messages[1]).toContain("Use defaultBackend()");+ expect(messages[1]).toContain("Vercel-compatible backend explicitly, such as vercel()");+ expect(messages[1]).toContain("Original");+ expect(messages[1]).toContain(cause.message);+ },+ );});function recordPrewarmInputs(inputs: SandboxBackendPrewarmInput[]) {@@ -82,12 +126,12 @@ function recordPrewarmInputs(inputs: SandboxBackendPrewarmInput[]) {};}-function createGraph(): ResolvedAgentGraphBundle {+function createGraph(backendName = "test"): ResolvedAgentGraphBundle {const backend: SandboxBackend = {async create() {throw new Error("Unexpected create call.");},- name: "test",+ name: backendName,async prewarm() {return { reused: true };},diff --git a/packages/eve/src/execution/sandbox/prewarm.ts b/packages/eve/src/execution/sandbox/prewarm.tsindex bc0303dce..41dfa411c 100644--- a/packages/eve/src/execution/sandbox/prewarm.ts+++ b/packages/eve/src/execution/sandbox/prewarm.ts@@ -113,10 +113,14 @@ export async function prewarmSandboxes(input: PrewarmSandboxesInput): Promise<vo},);} catch (error) {+ const prewarmError = formatPrewarmFailureForEnvironment({+ backendName: backend.name,+ error,+ });input.log?.(- `eve: failed to initialize sandbox template "${label}" on backend "${backend.name}": ${toErrorMessage(error)}`,+ `eve: failed to initialize sandbox template "${label}" on backend "${backend.name}": ${toErrorMessage(prewarmError)}`,);- throw error;+ throw prewarmError;}return result;}),@@ -344,3 +348,29 @@ function shouldLogSandboxPrewarmProgress(message: string): boolean {message !== "microsandbox runtime ready");}++function formatPrewarmFailureForEnvironment(input: {+ readonly backendName: string;+ readonly error: unknown;+}): unknown {+ if (!isVercelEnvironment() || !isLocalSandboxBackend(input.backendName)) {+ return input.error;+ }++ return new Error(+ `The ${input.backendName} sandbox backend is not available when deploying on Vercel. ` ++ "Vercel build containers cannot run local Docker containers or microsandbox VMs. " ++ "Use defaultBackend() so eve selects Vercel Sandbox on Vercel, or configure a " ++ "Vercel-compatible backend explicitly, such as vercel(). " ++ `Original ${input.backendName} error: ${toErrorMessage(input.error)}`,+ { cause: input.error },+ );+}++function isVercelEnvironment(): boolean {+ return Boolean(process.env.VERCEL?.trim());+}++function isLocalSandboxBackend(backendName: string): boolean {+ return backendName === "docker" || backendName === "microsandbox";+}