vercel/ai · error

${description} API key must be a string.

Error message

${description} API key must be a string.

What it means

loadFalApiKey throws a plain Error when the apiKey parameter is provided but is not a string (e.g. a number, object, or boolean). The fal provider requires the API key to be a string whether passed explicitly or loaded from the environment.

Source

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

   */
  textEmbeddingModel(modelId: string): never;
}

const defaultBaseURL = 'https://fal.run';

function loadFalApiKey({
  apiKey,
  description = 'fal.ai',
}: {
  apiKey: string | undefined;
  description?: string;
}): string {
  if (typeof apiKey === 'string') {
    return apiKey;
  }

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

  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.`,
    );
  }

View on GitHub (pinned to 69428b1f8b)

Solutions

1. Pass the API key as a string: createFal({ apiKey: '...' }).
2. Coerce/validate the config value with String(apiKey) only after confirming it is scalar and correct.
3. Remove the apiKey param entirely to fall back to FAL_API_KEY/FAL_KEY env vars.

Example fix

// before
createFal({ apiKey: process.env.FAL_KEY as unknown as number })
// after
const apiKey = process.env.FAL_KEY;
if (typeof apiKey !== 'string') throw new Error('FAL key missing');
createFal({ apiKey })

const key: unknown = config.falApiKey;
if (key != null && typeof key !== 'string') {
  throw new Error('fal apiKey config must be a string');
}

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

When it happens

Trigger: createFal({ apiKey: 12345 }) or createFal({ apiKey: someConfigObject }) where the value is non-null and not a string.

Common situations: Config values read from JSON/YAML that yield numbers, or passing a credentials object instead of the key string.

Related errors

• ${description} API key is missing. Pass it using the 'apiKey
• ${description} API key must be a string. The value of the en
• callers for tool "${toolName}" must be an array.
• ${description} API key is missing. Pass it using the 'apiKey
• ${description} API key must be a string.

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