vercel/ai · error · LoadAPIKeyError

${description} API key is missing. Pass it using the '${apiK

Error message

${description} API key is missing. Pass it using the '${apiKeyParameterName}' parameter or the ${environmentVariableName} environment variable.

What it means

loadApiKey found neither an apiKey parameter nor the configured environment variable (both null/undefined), so it throws LoadAPIKeyError naming the parameter and the expected environment variable. This is the standard 'credentials not configured' failure.

Source

Thrown at packages/provider-utils/src/load-api-key.ts:33

    return apiKey;
  }

  if (apiKey != null) {
    throw new LoadAPIKeyError({
      message: `${description} API key must be a string.`,
    });
  }

  if (typeof process === 'undefined') {
    throw new LoadAPIKeyError({
      message: `${description} API key is missing. Pass it using the '${apiKeyParameterName}' parameter. Environment variables are not supported in this environment.`,
    });
  }

  apiKey = process.env[environmentVariableName];

  if (apiKey == null) {
    throw new LoadAPIKeyError({
      message: `${description} API key is missing. Pass it using the '${apiKeyParameterName}' parameter or the ${environmentVariableName} environment variable.`,
    });
  }

  if (typeof apiKey !== 'string') {
    throw new LoadAPIKeyError({
      message: `${description} API key must be a string. The value of the ${environmentVariableName} environment variable is not a string.`,
    });
  }

  return apiKey;
}

View on GitHub (pinned to 69428b1f8b)

Solutions

Set the indicated environment variable (e.g. export OPENAI_API_KEY=sk-...) or add it to .env
Or pass the key explicitly: createOpenAI({ apiKey: 'sk-...' })
Verify the exact variable name and casing the provider expects
In CI/deployment, add the secret to the platform's environment configuration and redeploy

Example fix

// before
const anthropic = createAnthropic();
// after
const anthropic = createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

Defensive patterns

Strategy: validation

Validate before calling

const apiKey = process.env.OPENAI_API_KEY;
if (!apiKey) throw new Error('OPENAI_API_KEY is not set. Add it to .env or export it before starting.');
const provider = createOpenAI({ apiKey });

Type guard

function hasApiKey(value: unknown): value is string {
  return typeof value === 'string' && value.length > 0;
}

Try / catch

try {
  const provider = createOpenAI();
} catch (error) {
  if (/API key is missing/.test(String(error.message))) {
    console.error('Set OPENAI_API_KEY in your environment or pass it via createOpenAI({ apiKey })');
    process.exit(1);
  }
  throw error;
}

Prevention

Add a startup check that all required provider env vars are set
Keep .env files loaded (dotenv / framework auto-loading) and committed as .env.example
Match env var names exactly (including provider-specific prefixes like NEXT_PUBLIC_)
Configure secrets in CI and deployment platforms before first deploy

When it happens

Trigger: Calling a provider factory without an apiKey option while process.env[environmentVariableName] (e.g. OPENAI_API_KEY) is unset at call time.

Common situations: .env file not loaded (missing dotenv / Next.js env naming mismatch like NEXT_PUBLIC vs server-only); env var set in a different shell/session; CI pipeline missing the secret; variable defined but empty string treated as missing in some flows; deploying without configuring platform env vars.

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/64dd6b8706b99fec. Report an issue: GitHub.