What causes "Missing ${name}." in vercel/ai?

Read the thrown message to identify which variable is missing and set it in the shell or process environment before starting the bridge.

vercel/ai · critical

Missing ${name}.

Error message

Missing ${name}.

What it means

Thrown by requireEnvironmentVariable when a required environment variable is unset or an empty string. The bridge requires three at module load: AI_SDK_ACP_HOST_TOOLS_FILE, AI_SDK_ACP_HOST_TOOL_RELAY_URL, and AI_SDK_ACP_HOST_TOOL_RELAY_CREDENTIAL, so a missing variable fails startup immediately with 'Missing <NAME>.'.

Source

Thrown at packages/harness-acp/src/v1/bridge/host-tool-mcp.ts:178

  };
}

function readErrorMessage({
  value,
  status,
}: {
  value: unknown;
  status: number;
}): string {
  return isRecord(value) && typeof value.error === 'string'
    ? value.error
    : `Host tool relay returned HTTP ${status}.`;
}

function requireEnvironmentVariable({ name }: { name: string }): string {
  const value = env[name];
  if (value == null || value.length === 0) {
    throw new Error(`Missing ${name}.`);
  }
  return value;
}

function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
  return value != null && typeof value === 'object' && !Array.isArray(value);
}

View on GitHub (pinned to 69428b1f8b)

Solutions

Read the thrown message to identify which variable is missing and set it in the shell or process environment before starting the bridge.
If using a .env file, confirm it is actually loaded (dotenv or host app) and the variable name is spelled exactly as required.
Provision the relay credential (AI_SDK_ACP_HOST_TOOL_RELAY_CREDENTIAL) from your host/relay admin flow.
Verify with `printenv AI_SDK_ACP_HOST_TOOLS_FILE` (and the others) in the same environment that launches the process.

Example fix

// before: bare launch
node bridge.mjs
// after
AI_SDK_ACP_HOST_TOOLS_FILE=./host-tools.json \
AI_SDK_ACP_HOST_TOOL_RELAY_URL=http://127.0.0.1:8787 \
AI_SDK_ACP_HOST_TOOL_RELAY_CREDENTIAL=$RELAY_TOKEN \
node bridge.mjs

Defensive patterns

Strategy: validation

Validate before calling

const REQUIRED = [
  'AI_SDK_ACP_HOST_TOOLS_FILE',
  'AI_SDK_ACP_HOST_TOOL_RELAY_URL',
  'AI_SDK_ACP_HOST_TOOL_RELAY_CREDENTIAL',
];
for (const name of REQUIRED) {
  if (!process.env[name]) throw new Error(`Missing ${name}.`);
}

Try / catch

try {
  await import('./bridge-entry.js');
} catch (error) {
  if (error instanceof Error && error.message.startsWith('Missing ')) {
    console.error(`Configuration error: set ${error.message.slice('Missing '.length)} before starting the bridge.`);
    process.exitCode = 1;
  } else {
    throw error;
  }
}

Prevention

Launch the bridge only from the host environment that provisions the variables, never manually.
Add a startup preflight script that checks all three variables and fails fast with a clear message.
Keep variable names in a single shared constant/module to avoid typos.
In CI/deploy, verify secrets (relay credential) are injected before the process starts.

When it happens

Trigger: Starting the bridge process with any of AI_SDK_ACP_HOST_TOOLS_FILE, AI_SDK_ACP_HOST_TOOL_RELAY_URL, or AI_SDK_ACP_HOST_TOOL_RELAY_CREDENTIAL undefined, set to the empty string, or not exported into the process environment.

Common situations: Running the bridge outside the environment that provisions it (e.g. launching the MCP server manually from an editor instead of the host app); .env file not loaded; variable misspelled; credential not yet provisioned; CI/deploy environment lacking the secret.

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 vercel/ai@69428b1f8b (2026-08-30). Data as JSON: /api/errors/53e6c6f3f6b1275c. Report an issue: GitHub.