Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.ts
index 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.ts
index 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";
+}