Parallel API key is required. Pass { apiKey } or set the PAR

Error message

Parallel API key is required. Pass { apiKey } or set the PARALLEL_API_KEY environment variable.

What it means

getParallelClient resolves the Parallel API key from the explicit config or the PARALLEL_API_KEY env var; if neither is present it throws, since every request to the Parallel API needs authentication.

Source

Thrown at integrations/parallel/src/client.ts:10

import Parallel from 'parallel-web';
import type { ClientOptions } from 'parallel-web';

export type ParallelClientOptions = ClientOptions;
export type ParallelClient = Parallel;

export function getParallelClient(config?: ParallelClientOptions): ParallelClient {
  const apiKey = config?.apiKey ?? process.env.PARALLEL_API_KEY;
  if (!apiKey) {
    throw new Error('Parallel API key is required. Pass { apiKey } or set the PARALLEL_API_KEY environment variable.');
  }

  return new Parallel({ ...config, apiKey });
}

export function createLazyParallelClient(config?: ParallelClientOptions): () => ParallelClient {
  let client: ParallelClient | undefined;

  return () => {
    client ??= getParallelClient(config);
    return client;
  };
}

View on GitHub (pinned to 75dd419e61)

Solutions

Set PARALLEL_API_KEY in the environment (export or .env loaded before client creation).
Pass { apiKey: process.env.PARALLEL_API_KEY } (or a secret-manager value) explicitly to getParallelClient.
Check the deploy environment / CI secrets include PARALLEL_API_KEY.

Example fix

// before
const client = getParallelClient();
// after
const client = getParallelClient({ apiKey: process.env.PARALLEL_API_KEY! });

Defensive patterns

Strategy: validation

Validate before calling

const apiKey = config?.apiKey ?? process.env.PARALLEL_API_KEY;
if (!apiKey) throw new Error('Set PARALLEL_API_KEY before creating the Parallel client');

Type guard

function hasParallelApiKey(config?: { apiKey?: string }): config is { apiKey: string } {
  return typeof config?.apiKey === 'string' && config.apiKey.length > 0 || !!process.env.PARALLEL_API_KEY;
}

Try / catch

let client: ParallelClient;
try {
  client = getParallelClient();
} catch (e) {
  if ((e as Error).message.includes('Parallel API key is required')) {
    throw new Error('PARALLEL_API_KEY missing in this environment');
  }
  throw e;
}

Prevention

Load .env at process startup before any client creation
Add a startup env-var checklist (assert all required keys exist before serving traffic)
Add PARALLEL_API_KEY to deploy/CI secret configuration

When it happens

Trigger: Calling getParallelClient() or createLazyParallelClient()() with no apiKey option while process.env.PARALLEL_API_KEY is unset.

Common situations: .env file not loaded (dotenv not called before use); env var present locally but missing in the deploy environment/CI; typo like PARALLEL_API_KEYS; lazy client deferred until runtime where the env differs.

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 mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/17974dc39c527395. Report an issue: GitHub.