vercel/ai · error · Error

AI Gateway auth was selected but AI_GATEWAY_BASE_URL is miss

Error message

AI Gateway auth was selected but AI_GATEWAY_BASE_URL is missing from the Codex bridge environment.

What it means

The Codex bridge resolves AI Gateway credentials from its process environment. If AI_GATEWAY_API_KEY or AI_GATEWAY_BASE_URL is set (gateway auth selected) but AI_GATEWAY_BASE_URL is absent, it cannot build the gateway API base URL and throws. Gateway auth requires the base URL to configure the Codex process endpoint.

Source

Thrown at packages/harness-codex/src/bridge/index.ts:139

      'utf8',
    );
  }

  const codexConfig: Record<string, unknown> = {
    ...start.codexConfig,
    developer_instructions: [
      start.instructions,
      'Only respond with your `final` message once you have fully addressed the user request.',
    ]
      .filter((instruction): instruction is string => Boolean(instruction))
      .join('\n\n'),
    model_reasoning_summary: 'detailed',
  };

  const gatewayBaseUrl = procEnv.AI_GATEWAY_BASE_URL;
  const hasGatewayAuth = Boolean(procEnv.AI_GATEWAY_API_KEY || gatewayBaseUrl);
  if (hasGatewayAuth && !gatewayBaseUrl) {
    throw new Error(
      'AI Gateway auth was selected but AI_GATEWAY_BASE_URL is missing from the Codex bridge environment.',
    );
  }
  const apiBaseUrl = hasGatewayAuth ? gatewayBaseUrl : procEnv.OPENAI_BASE_URL;
  const codexModel =
    start.model && hasGatewayAuth && !start.model.includes('/')
      ? `openai/${start.model}`
      : start.model;
  /*
   * AI Gateway only returns populated reasoning summaries for its
   * creator-qualified model IDs. Codex treats qualified IDs as custom model
   * metadata, so its reasoning-summary capability must also be forced on for
   * the OpenAI Gateway route.
   */
  if (hasGatewayAuth && codexModel?.startsWith('openai/')) {
    codexConfig.model_supports_reasoning_summaries = true;
  }
  if (apiBaseUrl) {

View on GitHub (pinned to 69428b1f8b)

Solutions

Set AI_GATEWAY_BASE_URL in the environment passed to the Codex bridge process.
If you do not intend gateway auth, remove AI_GATEWAY_API_KEY so it falls back to OPENAI_BASE_URL.
Verify both AI_GATEWAY_* variables are exported in the same environment that spawns the bridge.

Example fix

// before
AI_GATEWAY_API_KEY=gw_...   # AI_GATEWAY_BASE_URL missing
// after
AI_GATEWAY_API_KEY=gw_...
AI_GATEWAY_BASE_URL=https://ai-gateway.example.com/v1

Defensive patterns

Strategy: validation

Validate before calling

const env = process.env;
if ((env.AI_GATEWAY_API_KEY || env.AI_GATEWAY_BASE_URL) && !env.AI_GATEWAY_BASE_URL) {
  throw new Error('AI_GATEWAY_BASE_URL is required when using AI Gateway auth');
}

Try / catch

try {
  await codex.start(startOpts);
} catch (e) {
  if (/AI_GATEWAY_BASE_URL is missing/.test(String(e?.message))) {
    // inject AI_GATEWAY_BASE_URL into the bridge env and retry
  } else throw e;
}

Prevention

Set AI_GATEWAY_API_KEY and AI_GATEWAY_BASE_URL together
Verify env vars in CI before spawning the bridge
Or unset AI_GATEWAY_API_KEY to use plain OPENAI_BASE_URL auth

When it happens

Trigger: Starting a codex turn with procEnv containing AI_GATEWAY_API_KEY set but AI_GATEWAY_BASE_URL unset; hasGatewayAuth becomes true via the API key while gatewayBaseUrl is undefined.

Common situations: Setting only the gateway API key in the environment that spawns the bridge, while AI_GATEWAY_BASE_URL lives in a different env (shell vs .env vs CI secret); typo'd or missing base-url variable in CI.

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/15e5c49ba8d864d4. Report an issue: GitHub.