{"record":{"id":"136329baa93bc652","repo":"mastra-ai/mastra","slug":"voyageai-api-key-is-required-set-voyage-api-key-e-136329","errorCode":null,"errorMessage":"VoyageAI API key is required. Set VOYAGE_API_KEY environment variable or pass apiKey in config.","messagePattern":"VoyageAI API key is required\\. Set VOYAGE_API_KEY environment variable or pass apiKey in config\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"embedders/voyageai/src/reranker.ts","lineNumber":54,"sourceCode":" *   'search query',\n *   scorer,\n *   { topK: 5 }\n * );\n * ```\n */\nexport class VoyageRelevanceScorer implements RelevanceScoreProvider {\n  readonly modelId: string;\n\n  private client: VoyageAIClient;\n  private config: VoyageRerankerConfig;\n\n  constructor(config: VoyageRerankerConfig) {\n    this.modelId = config.model;\n    this.config = config;\n\n    const apiKey = config.apiKey || process.env.VOYAGE_API_KEY;\n    if (!apiKey) {\n      throw new Error(\n        'VoyageAI API key is required. Set VOYAGE_API_KEY environment variable or pass apiKey in config.',\n      );\n    }\n\n    this.client = new VoyageAIClient({ apiKey, ...(config.baseUrl ? { baseUrl: config.baseUrl } : {}) });\n  }\n\n  /**\n   * Get relevance score between a query and a document.\n   *\n   * @param query - The search query (text1)\n   * @param document - The document to score (text2)\n   * @returns Relevance score between 0 and 1\n   */\n  async getRelevanceScore(query: string, document: string): Promise<number> {\n    const response = await this.client.rerank({\n      query,\n      documents: [document],","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/embedders/voyageai/src/reranker.ts#L36-L72","documentation":"The Voyage reranker client requires a VoyageAI API key, validated in the constructor from config.apiKey or the VOYAGE_API_KEY environment variable. If neither is present it throws before any rerank request.","triggerScenarios":"new VoyageReranker({ model }) with no apiKey configured and VOYAGE_API_KEY not set in the environment.","commonSituations":"Rerankers wired up in a different service than where the key is configured; serverless cold-start environment missing the secret; .env loaded after client construction.","solutions":["Pass apiKey in the VoyageReranker config object.","Export VOYAGE_API_KEY in the runtime environment.","Move client construction after environment/secret loading.","Confirm the key is valid — an empty-string env var also fails this check."],"exampleFix":"// before\nconst reranker = new VoyageReranker({ model: 'rerank-2' });\n// after\nconst reranker = new VoyageReranker({\n  model: 'rerank-2',\n  apiKey: process.env.VOYAGE_API_KEY,\n});","handlingStrategy":"validation","validationCode":"const apiKey = config.apiKey ?? process.env.VOYAGE_API_KEY;\nif (!apiKey) {\n  throw new Error('Set VOYAGE_API_KEY or pass apiKey before creating VoyageReranker');\n}\nconst reranker = new VoyageReranker({ ...config, apiKey });","typeGuard":"function hasVoyageApiKey(config: { apiKey?: string }): config is { apiKey: string } & typeof config {\n  return Boolean(config.apiKey ?? process.env.VOYAGE_API_KEY);\n}","tryCatchPattern":"let reranker;\ntry {\n  reranker = new VoyageReranker(config);\n} catch (err) {\n  if ((err as Error).message.includes('API key is required')) {\n    throw new Error('VoyageAI key missing for reranker: set VOYAGE_API_KEY or config.apiKey');\n  }\n  throw err;\n}","preventionTips":["Share a single factory that injects the key into all Voyage clients.","Set VOYAGE_API_KEY wherever the reranker service runs, not just where embeddings run.","Load secrets before client instantiation in serverless cold starts.","Validate key presence in health checks at boot."],"tags":["api-key","configuration","env-var","voyageai"],"backgroundTag":"missing-env-var","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}