{"record":{"id":"2743d9df4fa0198a","repo":"mastra-ai/mastra","slug":"updating-the-edge-config-alias-requires-a-vercel-a","errorCode":null,"errorMessage":"Updating the Edge Config alias requires a Vercel API token. Pass `alias.token`.","messagePattern":"Updating the Edge Config alias requires a Vercel API token\\. Pass `alias\\.token`\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"deployers/sandbox/src/alias.ts","lineNumber":11,"sourceCode":"import type { SandboxAliasOptions } from './types';\n\n/**\n * Upsert a Vercel Edge Config item so a stable key always points at the\n * current sandbox URL. Used for Tier 3 routing: apps read the key from Edge\n * Config (e.g. in middleware) instead of hardcoding the rotating sandbox URL.\n */\nexport async function updateEdgeConfigAlias(options: SandboxAliasOptions & { url: string }): Promise<void> {\n  const { token, teamId } = options;\n  if (!token) {\n    throw new Error('Updating the Edge Config alias requires a Vercel API token. Pass `alias.token`.');\n  }\n\n  const endpoint = new URL(`https://api.vercel.com/v1/edge-config/${options.edgeConfigId}/items`);\n  if (teamId) {\n    endpoint.searchParams.set('teamId', teamId);\n  }\n\n  const res = await fetch(endpoint, {\n    method: 'PATCH',\n    headers: {\n      Authorization: `Bearer ${token}`,\n      'Content-Type': 'application/json',\n    },\n    body: JSON.stringify({\n      items: [{ operation: 'upsert', key: options.key, value: options.url }],\n    }),\n    // Bounded so a hung Vercel API request can't keep `mastra build` open\n    // after the sandbox itself is already deployed.","sourceCodeStart":1,"sourceCodeEnd":29,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/deployers/sandbox/src/alias.ts#L1-L29","documentation":"updateEdgeConfigAlias writes the current sandbox URL into a Vercel Edge Config, and that write requires a Vercel API token. The library throws immediately, before any network call, when options.token is missing, to force explicit credential configuration. It fails fast instead of making an unauthenticated request that Vercel would reject.","triggerScenarios":"Calling updateEdgeConfigAlias() (directly or via deploy) with alias options that omit the token property — e.g. { edgeConfigId: 'ecfg_x', key: 'SANDBOX_URL' } without token.","commonSituations":"Happens when deploying the sandbox with an Edge Config alias configured but VERCEL_TOKEN not set in the environment and not passed in the alias config, or after copying config from a teammate who had the env var locally.","solutions":["Add token to the alias options, sourced from an env var: token: process.env.VERCEL_TOKEN.","Generate a Vercel API token in the Vercel dashboard and export it (e.g. VERCEL_TOKEN=...) before deploying.","If aliasing is optional for your setup, remove the alias config from the sandbox deploy options so updateEdgeConfigAlias isn't called."],"exampleFix":"// before\nawait deploy({ alias: { edgeConfigId: 'ecfg_123', key: 'SANDBOX_URL' } });\n// after\nawait deploy({ alias: { edgeConfigId: 'ecfg_123', key: 'SANDBOX_URL', token: process.env.VERCEL_TOKEN } });","handlingStrategy":"validation","validationCode":"if (!process.env.VERCEL_TOKEN) {\n  throw new Error('Set VERCEL_TOKEN before deploying with an Edge Config alias');\n}","typeGuard":"function hasAliasToken(o: { token?: string }): o is { token: string } & typeof o {\n  return typeof o.token === 'string' && o.token.length > 0;\n}","tryCatchPattern":"try {\n  await updateEdgeConfigAlias({ ...aliasOpts, url });\n} catch (err) {\n  if ((err as Error).message.includes('requires a Vercel API token')) {\n    console.error('Add alias.token (VERCEL_TOKEN) to your sandbox config.');\n  }\n  throw err;\n}","preventionTips":["Store VERCEL_TOKEN in CI secrets and local .env and validate at config load time.","Validate alias options (token, edgeConfigId, key) before starting a deploy.","Document the alias.token requirement wherever the alias option is surfaced."],"tags":["vercel","edge-config","missing-token","configuration"],"backgroundTag":"missing-api-token","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}