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. Environment variables are not supported in this environment.

What it means

loadApiKey could not find the API key: no apiKey parameter was provided and `process` is undefined (edge/browser/serverless runtimes without Node's process global), so environment variables cannot be consulted. It throws LoadAPIKeyError telling you to pass the key explicitly via the named parameter.

Source

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

  description,
}: {
  apiKey: string | undefined;
  environmentVariableName: string;
  apiKeyParameterName?: string;
  description: string;
}): string {
  if (typeof apiKey === 'string') {
    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.`,
    });
  }

View on GitHub (pinned to 69428b1f8b)

Solutions

Pass the key explicitly: createOpenAI({ apiKey: env.MY_API_KEY })
In Next.js, expose the variable server-side and pass it in a route handler/server action instead of relying on process.env in edge/browser code
Enable Node.js runtime/compat if the deployment platform supports it
Ensure the value you read from the platform's env bindings (e.g. worker env object) is actually forwarded to the factory

Example fix

// before (edge runtime)
const openai = createOpenAI();
// after
const openai = createOpenAI({ apiKey: env.OPENAI_API_KEY });

Defensive patterns

Strategy: validation

Validate before calling

if (typeof process === 'undefined') {
  if (!env.OPENAI_API_KEY) throw new Error('Pass apiKey explicitly: process.env is unavailable in this runtime');
}
const provider = createOpenAI({ apiKey: env.OPENAI_API_KEY });

Type guard

function canUseProcessEnv(): boolean {
  return typeof process !== 'undefined' && typeof process.env === 'object';
}

Try / catch

try {
  const provider = createOpenAI();
} catch (error) {
  if (/API key is missing/.test(String(error.message))) {
    throw new Error('Set OPENAI_API_KEY or pass createOpenAI({ apiKey }) — env vars unsupported here');
  }
  throw error;
}

Prevention

In edge/browser code, always pass the key explicitly from platform env bindings
Never rely on process.env in Edge Runtime, Workers, or client bundles
Fail fast at boot with your own env check for required keys

When it happens

Trigger: Creating a provider instance (e.g. createOpenAI()) with no apiKey in an environment where `typeof process === 'undefined'` — such as Edge Runtime, Vercel Edge Functions configured without Node compat, browsers, or workers — and no key was passed in options.

Common situations: Deploying to Edge runtime after developing locally with env vars; forgetting that .env loading doesn't exist in the browser; Cloudflare Workers without env binding wired to the provider factory.

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/94e2fb8341450fad. Report an issue: GitHub.