Perplexity API key is required. Pass { apiKey } or set the P

Error message

Perplexity API key is required. Pass { apiKey } or set the PERPLEXITY_API_KEY (or PPLX_API_KEY) environment variable.

What it means

resolveApiKey picks the Perplexity key from the explicit argument, then PERPLEXITY_API_KEY, then PPLX_API_KEY. If all three are missing, any Perplexity client/tool creation throws this error because the API cannot be called unauthenticated.

Source

Thrown at integrations/perplexity/src/client.ts:45

export type PerplexitySearchResponse = {
  id?: string;
  results: PerplexitySearchResultItem[];
};

export type PerplexitySearchRequest = {
  query: string;
  max_results?: number;
  max_tokens_per_page?: number;
  search_domain_filter?: string[];
  search_recency_filter?: 'hour' | 'day' | 'week' | 'month' | 'year';
  search_after_date_filter?: string;
  search_before_date_filter?: string;
};

function resolveApiKey(explicit?: string): string {
  const key = explicit ?? process.env.PERPLEXITY_API_KEY ?? process.env.PPLX_API_KEY;
  if (!key) {
    throw new Error(
      'Perplexity API key is required. Pass { apiKey } or set the PERPLEXITY_API_KEY (or PPLX_API_KEY) environment variable.',
    );
  }
  return key;
}

export async function perplexitySearchRequest(
  body: PerplexitySearchRequest,
  options?: PerplexityClientOptions,
): Promise<PerplexitySearchResponse> {
  const apiKey = resolveApiKey(options?.apiKey);
  const baseUrl = options?.baseUrl ?? DEFAULT_BASE_URL;
  const fetchImpl = options?.fetch ?? fetch;

  const response = await fetchImpl(`${baseUrl.replace(/\/$/, '')}/search`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',

View on GitHub (pinned to 75dd419e61)

Solutions

Set PERPLEXITY_API_KEY in the environment (preferred name).
Or set PPLX_API_KEY if that is the convention used by your infra.
Or pass apiKey explicitly when creating the client/tools.

Example fix

// before (shell)
PERPLEXITY=plx_key npm start  # wrong var name
// after
PERPLEXITY_API_KEY=plx_key npm start

Defensive patterns

Strategy: validation

Validate before calling

const key = explicit ?? process.env.PERPLEXITY_API_KEY ?? process.env.PPLX_API_KEY;
if (!key) throw new Error('Set PERPLEXITY_API_KEY (or PPLX_API_KEY) before using Perplexity');

Type guard

function hasPerplexityKey(explicit?: string): boolean {
  return !!explicit || !!process.env.PERPLEXITY_API_KEY || !!process.env.PPLX_API_KEY;
}

Try / catch

try {
  const client = createPerplexityClient();
} catch (e) {
  if ((e as Error).message.includes('Perplexity API key is required')) {
    throw new Error('PERPLEXITY_API_KEY / PPLX_API_KEY not configured');
  }
  throw e;
}

Prevention

Standardize on PERPLEXITY_API_KEY across environments
Assert required env keys at app boot
Keep env var names documented in deployment templates

When it happens

Trigger: Constructing the Perplexity client/tools via resolveApiKey with no explicit key while both PERPLEXITY_API_KEY and PPLX_API_KEY are unset in the environment.

Common situations: Only the legacy PPLX_API_KEY name set in a newer codebase, or vice versa; .env not loaded before client construction; key present in local shell but absent in production runtime.

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/871add1f8df5de34. Report an issue: GitHub.