{"record":{"id":"871add1f8df5de34","repo":"mastra-ai/mastra","slug":"perplexity-api-key-is-required-pass-apikey-or","errorCode":null,"errorMessage":"Perplexity API key is required. Pass { apiKey } or set the PERPLEXITY_API_KEY (or PPLX_API_KEY) environment variable.","messagePattern":"Perplexity API key is required\\. Pass (.+?) or set the PERPLEXITY_API_KEY \\(or PPLX_API_KEY\\) environment variable\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"integrations/perplexity/src/client.ts","lineNumber":45,"sourceCode":"export type PerplexitySearchResponse = {\n  id?: string;\n  results: PerplexitySearchResultItem[];\n};\n\nexport type PerplexitySearchRequest = {\n  query: string;\n  max_results?: number;\n  max_tokens_per_page?: number;\n  search_domain_filter?: string[];\n  search_recency_filter?: 'hour' | 'day' | 'week' | 'month' | 'year';\n  search_after_date_filter?: string;\n  search_before_date_filter?: string;\n};\n\nfunction resolveApiKey(explicit?: string): string {\n  const key = explicit ?? process.env.PERPLEXITY_API_KEY ?? process.env.PPLX_API_KEY;\n  if (!key) {\n    throw new Error(\n      'Perplexity API key is required. Pass { apiKey } or set the PERPLEXITY_API_KEY (or PPLX_API_KEY) environment variable.',\n    );\n  }\n  return key;\n}\n\nexport async function perplexitySearchRequest(\n  body: PerplexitySearchRequest,\n  options?: PerplexityClientOptions,\n): Promise<PerplexitySearchResponse> {\n  const apiKey = resolveApiKey(options?.apiKey);\n  const baseUrl = options?.baseUrl ?? DEFAULT_BASE_URL;\n  const fetchImpl = options?.fetch ?? fetch;\n\n  const response = await fetchImpl(`${baseUrl.replace(/\\/$/, '')}/search`, {\n    method: 'POST',\n    headers: {\n      'Content-Type': 'application/json',","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/integrations/perplexity/src/client.ts#L27-L63","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before (shell)\nPERPLEXITY=plx_key npm start  # wrong var name\n// after\nPERPLEXITY_API_KEY=plx_key npm start","handlingStrategy":"validation","validationCode":"const key = explicit ?? process.env.PERPLEXITY_API_KEY ?? process.env.PPLX_API_KEY;\nif (!key) throw new Error('Set PERPLEXITY_API_KEY (or PPLX_API_KEY) before using Perplexity');","typeGuard":"function hasPerplexityKey(explicit?: string): boolean {\n  return !!explicit || !!process.env.PERPLEXITY_API_KEY || !!process.env.PPLX_API_KEY;\n}","tryCatchPattern":"try {\n  const client = createPerplexityClient();\n} catch (e) {\n  if ((e as Error).message.includes('Perplexity API key is required')) {\n    throw new Error('PERPLEXITY_API_KEY / PPLX_API_KEY not configured');\n  }\n  throw e;\n}","preventionTips":["Standardize on PERPLEXITY_API_KEY across environments","Assert required env keys at app boot","Keep env var names documented in deployment templates"],"tags":["api-key","configuration","environment","perplexity"],"backgroundTag":"missing-api-key","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}