createSandboxProxy requires an Edge Config connection string

Error message

createSandboxProxy requires an Edge Config connection string (EDGE_CONFIG).

What it means

createSandboxProxy needs an Edge Config connection string to read sandbox metadata (connection/key/token) when proxying requests, and none was found. It checks the options.edgeConfig value first, then the EDGE_CONFIG environment variable. This is thrown only in server-side code (assertServerOnly already passed).

Source

Thrown at deployers/sandbox/src/client/index.ts:286

 * request falls through.
 *
 * ```typescript
 * // middleware.ts
 * export const middleware = createSandboxProxy({ key: 'my-preview' });
 * export const config = { matcher: '/api/:path*' };
 * ```
 */
export function createSandboxProxy(
  options: CreateSandboxProxyOptions,
): (request: Request) => Promise<Response | undefined> {
  // Reads (and would transmit) the Edge Config bearer token — same
  // server-only contract as the rest of this module.
  assertServerOnly();

  return async (request: Request): Promise<Response | undefined> => {
    const connection = options.edgeConfig ?? process.env.EDGE_CONFIG;
    if (!connection) {
      throw new Error('createSandboxProxy requires an Edge Config connection string (EDGE_CONFIG).');
    }

    const conn = new URL(connection);
    const token = conn.searchParams.get('token');
    const itemUrl = new URL(`${conn.origin}${conn.pathname}/item/${encodeURIComponent(options.key)}`);

    const res = await fetch(itemUrl, { headers: { Authorization: `Bearer ${token}` } });
    if (!res.ok) {
      return undefined;
    }
    const sandboxUrl: unknown = await res.json();
    if (typeof sandboxUrl !== 'string' || !sandboxUrl) {
      return undefined;
    }

    const incoming = new URL(request.url);
    const target = new URL(incoming.pathname + incoming.search, sandboxUrl);

View on GitHub (pinned to 75dd419e61)

Solutions

Set EDGE_CONFIG in the environment where the proxy runs (Vercel project env vars or .env)
Pass the connection string explicitly: createSandboxProxy({ edgeConfig: process.env.MY_EDGE_CONFIG, ... })
Copy the Edge Config connection string from the Vercel dashboard (Store → Edge Config)
If the proxy is being invoked from the client by mistake, move it to a server-only route handler

Example fix

// before
export const proxy = createSandboxProxy({ key: 'sandboxes' });
// after
export const proxy = createSandboxProxy({
  key: 'sandboxes',
  edgeConfig: process.env.EDGE_CONFIG,
});

Defensive patterns

Strategy: validation

Validate before calling

if (!process.env.EDGE_CONFIG) {
  throw new Error('EDGE_CONFIG must be set where createSandboxProxy runs (server-side)');
}
new URL(process.env.EDGE_CONFIG); // sanity-check the connection string parses

Prevention

Set EDGE_CONFIG in every environment the proxy deploys to (including preview)
Pass edgeConfig explicitly in options when self-hosting
Keep proxy code in server-only route handlers

When it happens

Trigger: Invoking the proxy handler returned by createSandboxProxy in a Next.js/serverless route without passing { edgeConfig } to createSandboxProxy and without the EDGE_CONFIG env var set in the deployed environment.

Common situations: Working locally where EDGE_CONFIG is only set in the Vercel project dashboard (not in .env.local); deploying to a non-Vercel environment where Vercel doesn't inject EDGE_CONFIG; forgetting to pass edgeConfig in options when self-hosting.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/b72f886a9bb78190. Report an issue: GitHub.