vercel/ai · error · Error

AI Gateway authentication was selected, but neither AI_GATEW

Error message

AI Gateway authentication was selected, but neither AI_GATEWAY_API_KEY nor VERCEL_OIDC_TOKEN is set.

What it means

resolveACPProviderAuthentication throws this when AI Gateway authentication mode is explicitly selected (or required by the resolved mode) but no gateway credential can be found in the environment. The resolver looks for AI_GATEWAY_API_KEY first and falls back to VERCEL_OIDC_TOKEN; if both are absent it cannot construct an 'ai-gateway' providerAuthentication and refuses to continue. This prevents silently launching an ACP harness whose downstream provider calls would fail authentication.

Source

Thrown at packages/harness-acp/src/acp-auth.ts:150

  const gateway =
    compatibility?.type === 'ai-gateway'
      ? {
          apiKey: resolveGatewayCredential({
            env: resolvedEnv,
            credentialSource: compatibility.credentialSource,
          }),
          baseUrl: compatibility.baseUrl,
        }
      : getAiGatewayAuthFromEnv({ env: resolvedEnv });
  const apiKey = gateway.apiKey;
  if (compatibility == null && mode === 'auto' && apiKey == null) {
    return {
      providerAuthentication: { type: 'direct' },
      env: clientAppEnv,
    };
  }
  if (apiKey == null) {
    throw new Error(
      'AI Gateway authentication was selected, but neither AI_GATEWAY_API_KEY nor VERCEL_OIDC_TOKEN is set.',
    );
  }

  return {
    providerAuthentication: {
      type: 'ai-gateway',
      env:
        compatibility?.type === 'ai-gateway'
          ? compatibility.env
          : providerAuthentication.gateway.env,
    },
    env: {
      AI_SDK_ACP_GATEWAY_API_KEY: apiKey,
      AI_SDK_ACP_GATEWAY_BASE_URL: gateway.baseUrl,
      ...clientAppEnv,
    },
  };

View on GitHub (pinned to 69428b1f8b)

Solutions

Set AI_GATEWAY_API_KEY in the environment (e.g. from a Vercel access token) before creating the harness.
Run on Vercel (or attach OIDC) so VERCEL_OIDC_TOKEN is available.
If gateway auth is not needed, switch configuration to direct provider authentication (auth: 'direct' or providerAuthentication { type: 'direct' }).
Verify the env vars are spelled correctly and actually passed into the harness env record, not just the shell.

Example fix

// before
const harness = createCodexACP({ auth: 'ai-gateway' }); // throws: no credentials
// after
process.env.AI_GATEWAY_API_KEY = '<key>'; // or export in shell / CI secrets
const harness = createCodexACP({ auth: 'ai-gateway' });

Defensive patterns

Strategy: validation

Validate before calling

function hasGatewayCredential(env: NodeJS.ProcessEnv): boolean {
  return env.AI_GATEWAY_API_KEY != null || env.VERCEL_OIDC_TOKEN != null;
}
if (!hasGatewayCredential(process.env)) {
  throw new Error('Set AI_GATEWAY_API_KEY (or run on Vercel for VERCEL_OIDC_TOKEN) before using AI Gateway auth.');
}

Try / catch

try {
  const harness = createCodexACP({ auth: 'ai-gateway' });
} catch (error) {
  if (error instanceof Error && error.message.includes('AI Gateway authentication was selected')) {
    // fall back to direct auth or surface a config error
  }
  throw error;
}

Prevention

Run `vercel env pull` locally and configure AI_GATEWAY_API_KEY as a CI secret.
Assert required env vars at process startup before constructing harnesses.
Use direct provider authentication when gateway credentials are not available.

When it happens

Trigger: Calling createACP/createCodexACP/etc. with auth configured for AI Gateway (auth.mode not 'direct' and not auto-with-direct-fallback, or providerAuthentication of type 'ai-gateway') while the process env lacks both AI_GATEWAY_API_KEY and VERCEL_OIDC_TOKEN. Also occurs when compatibility?.type === 'ai-gateway' and resolveGatewayCredential returns null.

Common situations: Deploying locally without `vercel env pull`; CI jobs where AI_GATEWAY_API_KEY secret is not configured; running in a non-Vercel environment where VERCEL_OIDC_TOKEN is never injected; typos in the env var name; forgetting to pass an env record containing the key into the harness settings.

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.

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

AI-assisted analysis of vercel/ai@69428b1f8b (2026-08-30). Data as JSON: /api/errors/9bc9e17033b21099. Report an issue: GitHub.