{"record":{"id":"b72f886a9bb78190","repo":"mastra-ai/mastra","slug":"createsandboxproxy-requires-an-edge-config-connect","errorCode":null,"errorMessage":"createSandboxProxy requires an Edge Config connection string (EDGE_CONFIG).","messagePattern":"createSandboxProxy requires an Edge Config connection string \\(EDGE_CONFIG\\)\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"deployers/sandbox/src/client/index.ts","lineNumber":286,"sourceCode":" * request falls through.\n *\n * ```typescript\n * // middleware.ts\n * export const middleware = createSandboxProxy({ key: 'my-preview' });\n * export const config = { matcher: '/api/:path*' };\n * ```\n */\nexport function createSandboxProxy(\n  options: CreateSandboxProxyOptions,\n): (request: Request) => Promise<Response | undefined> {\n  // Reads (and would transmit) the Edge Config bearer token — same\n  // server-only contract as the rest of this module.\n  assertServerOnly();\n\n  return async (request: Request): Promise<Response | undefined> => {\n    const connection = options.edgeConfig ?? process.env.EDGE_CONFIG;\n    if (!connection) {\n      throw new Error('createSandboxProxy requires an Edge Config connection string (EDGE_CONFIG).');\n    }\n\n    const conn = new URL(connection);\n    const token = conn.searchParams.get('token');\n    const itemUrl = new URL(`${conn.origin}${conn.pathname}/item/${encodeURIComponent(options.key)}`);\n\n    const res = await fetch(itemUrl, { headers: { Authorization: `Bearer ${token}` } });\n    if (!res.ok) {\n      return undefined;\n    }\n    const sandboxUrl: unknown = await res.json();\n    if (typeof sandboxUrl !== 'string' || !sandboxUrl) {\n      return undefined;\n    }\n\n    const incoming = new URL(request.url);\n    const target = new URL(incoming.pathname + incoming.search, sandboxUrl);\n","sourceCodeStart":268,"sourceCodeEnd":304,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/deployers/sandbox/src/client/index.ts#L268-L304","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nexport const proxy = createSandboxProxy({ key: 'sandboxes' });\n// after\nexport const proxy = createSandboxProxy({\n  key: 'sandboxes',\n  edgeConfig: process.env.EDGE_CONFIG,\n});","handlingStrategy":"validation","validationCode":"if (!process.env.EDGE_CONFIG) {\n  throw new Error('EDGE_CONFIG must be set where createSandboxProxy runs (server-side)');\n}\nnew URL(process.env.EDGE_CONFIG); // sanity-check the connection string parses","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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"],"tags":["edge-config","missing-env-var","sandbox","proxy"],"backgroundTag":"missing-env-var","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}