${description} API key is missing. Pass it using the 'apiKey

Error message

${description} API key is missing. Pass it using the 'apiKey' parameter or set either the FAL_API_KEY or FAL_KEY environment variable.

What it means

loadFalApiKey throws this when no apiKey parameter was supplied and neither FAL_API_KEY nor FAL_KEY environment variables are set. The fal provider checks both variables in order before giving up.

Source

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

  }

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

  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);

View on GitHub (pinned to 69428b1f8b)

Solutions

Set the FAL_API_KEY (or FAL_KEY) environment variable.
Pass the key explicitly via createFal({ apiKey: '...' }).
Verify .env is loaded (e.g. dotenv/config) and the variable name matches exactly.

Example fix

// before
const fal = createFal(); // no key anywhere
// after (shell)
export FAL_API_KEY="fal_..."
// or
const fal = createFal({ apiKey: process.env.MY_FAL_KEY! });

Defensive patterns

Strategy: validation

Validate before calling

if (!process.env.FAL_API_KEY && !process.env.FAL_KEY) {
  throw new Error('Set FAL_API_KEY or FAL_KEY before creating the fal provider');
}

Try / catch

try {
  fal = createFal();
} catch (e) {
  if ((e as Error).message.includes('API key is missing')) {
    console.error('Missing fal credentials: set FAL_API_KEY or FAL_KEY');
    process.exit(1);
  }
  throw e;
}

Prevention

Add FAL_API_KEY to .env and commit a .env.example.
Load dotenv at process startup before creating providers.
Check secrets are present in CI with a preflight validation script.

When it happens

Trigger: createFal() (no apiKey) executed in a Node-like environment where process.env.FAL_API_KEY and process.env.FAL_KEY are both undefined.

Common situations: Forgetting to add the key to .env, not loading .env (dotenv not invoked), or CI environments lacking the secret.

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

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