vercel/ai · error · LoadAPIKeyError

${description} API key must be a string.

Error message

${description} API key must be a string.

What it means

loadApiKey validates the API key passed to a provider factory. If you supplied a value that is neither a string nor null/undefined (e.g. a number, object, or boolean), it throws LoadAPIKeyError with this message. It prevents silently sending an invalid credential type in request headers.

Source

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

import { LoadAPIKeyError } from '@ai-sdk/provider';

export function loadApiKey({
  apiKey,
  environmentVariableName,
  apiKeyParameterName = 'apiKey',
  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.`,
    });
  }

View on GitHub (pinned to 69428b1f8b)

Solutions

1. Pass the API key as a plain string: apiKey: 'sk-...'
2. Coerce env/config values to string before passing (String(value) after null check)
3. If you have no key, omit the option so loadApiKey falls back to the environment variable
4. Check config parsing (dotenv, YAML, CLI args) for type coercion issues

Example fix

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

const apiKey = typeof cfg.apiKey === 'string' ? cfg.apiKey : process.env.OPENAI_API_KEY;
if (typeof apiKey !== 'string') throw new Error('apiKey must be a string');
const provider = createOpenAI({ apiKey });

function isApiKey(value: unknown): value is string {
  return typeof value === 'string';
}

try {
  const provider = createOpenAI({ apiKey: config.apiKey });
} catch (error) {
  if (LoadAPIKeyError.isInstance?.(error) || /API key must be a string/.test(String(error.message))) {
    throw new Error('Config error: apiKey must be a string, got ' + typeof config.apiKey);
  }
  throw error;
}

When it happens

Trigger: Calling a provider factory like createOpenAI({ apiKey: 12345 }) or createAnthropic({ apiKey: { key: '...' } }) with a non-string, non-nullish apiKey option.

Common situations: Reading the key from config with the wrong type (YAML/JSON numbers), passing an API-key wrapper object, using `apiKey: false` or a placeholder constant, template/config tooling injecting wrong types.

Related errors

• Invalid argument for parameter output: Invalid output type.
• Continuation maxAgeMs must be a positive integer.
• ${description} API key must be a string.
• ${description} API key is missing. Pass it using the 'apiKey
• ACP credentialEnv and credentialBrokering must be configured

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