Updating the Edge Config alias requires a Vercel API token.

Error message

Updating the Edge Config alias requires a Vercel API token. Pass `alias.token`.

What it means

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.

Source

Thrown at deployers/sandbox/src/alias.ts:11

import type { SandboxAliasOptions } from './types';

/**
 * Upsert a Vercel Edge Config item so a stable key always points at the
 * current sandbox URL. Used for Tier 3 routing: apps read the key from Edge
 * Config (e.g. in middleware) instead of hardcoding the rotating sandbox URL.
 */
export async function updateEdgeConfigAlias(options: SandboxAliasOptions & { url: string }): Promise<void> {
  const { token, teamId } = options;
  if (!token) {
    throw new Error('Updating the Edge Config alias requires a Vercel API token. Pass `alias.token`.');
  }

  const endpoint = new URL(`https://api.vercel.com/v1/edge-config/${options.edgeConfigId}/items`);
  if (teamId) {
    endpoint.searchParams.set('teamId', teamId);
  }

  const res = await fetch(endpoint, {
    method: 'PATCH',
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      items: [{ operation: 'upsert', key: options.key, value: options.url }],
    }),
    // Bounded so a hung Vercel API request can't keep `mastra build` open
    // after the sandbox itself is already deployed.

View on GitHub (pinned to 75dd419e61)

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.

Example fix

// before
await deploy({ alias: { edgeConfigId: 'ecfg_123', key: 'SANDBOX_URL' } });
// after
await deploy({ alias: { edgeConfigId: 'ecfg_123', key: 'SANDBOX_URL', token: process.env.VERCEL_TOKEN } });

Defensive patterns

Strategy: validation

Validate before calling

if (!process.env.VERCEL_TOKEN) {
  throw new Error('Set VERCEL_TOKEN before deploying with an Edge Config alias');
}

Type guard

function hasAliasToken(o: { token?: string }): o is { token: string } & typeof o {
  return typeof o.token === 'string' && o.token.length > 0;
}

Try / catch

try {
  await updateEdgeConfigAlias({ ...aliasOpts, url });
} catch (err) {
  if ((err as Error).message.includes('requires a Vercel API token')) {
    console.error('Add alias.token (VERCEL_TOKEN) to your sandbox config.');
  }
  throw err;
}

Prevention

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.

When it happens

Trigger: Calling updateEdgeConfigAlias() (directly or via deploy) with alias options that omit the token property — e.g. { edgeConfigId: 'ecfg_x', key: 'SANDBOX_URL' } without token.

Common situations: 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.

Related errors

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