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

Error message

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

What it means

loadFalApiKey throws this when the resolved environment variable (FAL_API_KEY or FAL_KEY) exists but its value is not a string. This guards against non-string env values that some runtimes or test setups can inject.

Source

Thrown at packages/fal/src/fal-provider.ts:121

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

  let envApiKey = process.env.FAL_API_KEY;
  if (envApiKey == null) {
    envApiKey = process.env.FAL_KEY;
  }

  if (envApiKey == null) {
    throw new Error(
      `${description} API key is missing. Pass it using the 'apiKey' parameter or set either the FAL_API_KEY or FAL_KEY environment variable.`,
    );
  }

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

  return envApiKey;
}

/**
 * Create a fal.ai provider instance.
 */
export function createFal(options: FalProviderSettings = {}): FalProvider {
  const baseURL = withoutTrailingSlash(options.baseURL ?? defaultBaseURL);
  const getHeaders = () =>
    withUserAgentSuffix(
      {
        Authorization: `Key ${loadFalApiKey({
          apiKey: options.apiKey,
        })}`,

View on GitHub (pinned to 69428b1f8b)

Solutions

Set the env variable to a plain string value.
Fix test mocks so process.env.FAL_API_KEY is a string.
Bypass env lookup by passing createFal({ apiKey: '...' }) with an explicit string.

Example fix

// before (test mock)
process.env.FAL_API_KEY = { token: 'x' } as any;
// after
process.env.FAL_API_KEY = 'fal_key_string';

Defensive patterns

Strategy: type-guard

Validate before calling

const envKey: unknown = process.env.FAL_API_KEY ?? process.env.FAL_KEY;
if (envKey != null && typeof envKey !== 'string') {
  throw new Error('FAL_API_KEY/FAL_KEY env value must be a string');
}

Type guard

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

Prevention

Mock process.env only with string values in tests.
Restore env vars after each test (afterEach / vi.unstubAllEnvs).
Avoid assigning objects into process.env anywhere in app code.

When it happens

Trigger: process.env.FAL_API_KEY or FAL_KEY is set to a non-string value (e.g. an object assigned directly in tests or a runtime exposing non-string env entries).

Common situations: Test code that mocks process.env with non-string values, or exotic runtime environments where env entries are not plain strings.

Related errors

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