vercel/ai · error · LoadAPIKeyError

${description} API key must be a string. The value of the ${

Error message

${description} API key must be a string. The value of the ${environmentVariableName} environment variable is not a string.

What it means

loadApiKey resolved an API key from the environment variable, but the value stored there is not a string (e.g. a number or object leaked in through a mocked/patched process.env). It throws LoadAPIKeyError to stop a non-string credential being used.

Source

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

    });
  }

  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

1. Fix whatever assigned the non-string value: env vars must be strings (String(value))
2. In tests, set process.env values as strings (or use vi.stubEnv with a string)
3. Pass the key explicitly as a string instead of relying on the environment
4. Check for config loaders that write parsed objects/numbers into process.env

Example fix

// before (test setup)
process.env.OPENAI_API_KEY = 12345;
// after
process.env.OPENAI_API_KEY = 'sk-test-12345';

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

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

try {
  const provider = createOpenAI();
} catch (error) {
  if (/environment variable is not a string/.test(String(error.message))) {
    throw new Error('process.env was patched with non-string values — check test setup/config loader');
  }
  throw error;
}

When it happens

Trigger: process.env[environmentVariableName] is set to a non-string value — typically in tests where process.env was assigned non-string values, or in runtimes that type env entries loosely.

Common situations: Unit tests assigning process.env.OPENAI_API_KEY = 12345; mocked env objects in test setup; scripts that patch process.env with parsed config objects.

Related errors

• ${description} API key must be a string. The value of the en
• ACP runtime environment key ${JSON.stringify(key)} cannot be
• ACP runtime environment key ${JSON.stringify(key)} cannot be
• ACP runtime environment key ${JSON.stringify(key)} cannot be
• ACP environment variable name is invalid: ${JSON.stringify(k

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