VoyageAI API key is required. Set VOYAGE_API_KEY environment

Error message

VoyageAI API key is required. Set VOYAGE_API_KEY environment variable or pass apiKey in config.

What it means

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.

Source

Thrown at embedders/voyageai/src/reranker.ts:54

 *   'search query',
 *   scorer,
 *   { topK: 5 }
 * );
 * ```
 */
export class VoyageRelevanceScorer implements RelevanceScoreProvider {
  readonly modelId: string;

  private client: VoyageAIClient;
  private config: VoyageRerankerConfig;

  constructor(config: VoyageRerankerConfig) {
    this.modelId = config.model;
    this.config = config;

    const apiKey = config.apiKey || process.env.VOYAGE_API_KEY;
    if (!apiKey) {
      throw new Error(
        'VoyageAI API key is required. Set VOYAGE_API_KEY environment variable or pass apiKey in config.',
      );
    }

    this.client = new VoyageAIClient({ apiKey, ...(config.baseUrl ? { baseUrl: config.baseUrl } : {}) });
  }

  /**
   * Get relevance score between a query and a document.
   *
   * @param query - The search query (text1)
   * @param document - The document to score (text2)
   * @returns Relevance score between 0 and 1
   */
  async getRelevanceScore(query: string, document: string): Promise<number> {
    const response = await this.client.rerank({
      query,
      documents: [document],

View on GitHub (pinned to 75dd419e61)

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.

Example fix

// before
const reranker = new VoyageReranker({ model: 'rerank-2' });
// after
const reranker = new VoyageReranker({
  model: 'rerank-2',
  apiKey: process.env.VOYAGE_API_KEY,
});

Defensive patterns

Strategy: validation

Validate before calling

const apiKey = config.apiKey ?? process.env.VOYAGE_API_KEY;
if (!apiKey) {
  throw new Error('Set VOYAGE_API_KEY or pass apiKey before creating VoyageReranker');
}
const reranker = new VoyageReranker({ ...config, apiKey });

Type guard

function hasVoyageApiKey(config: { apiKey?: string }): config is { apiKey: string } & typeof config {
  return Boolean(config.apiKey ?? process.env.VOYAGE_API_KEY);
}

Try / catch

let reranker;
try {
  reranker = new VoyageReranker(config);
} catch (err) {
  if ((err as Error).message.includes('API key is required')) {
    throw new Error('VoyageAI key missing for reranker: set VOYAGE_API_KEY or config.apiKey');
  }
  throw err;
}

Prevention

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.

When it happens

Trigger: new VoyageReranker({ model }) with no apiKey configured and VOYAGE_API_KEY not set in the environment.

Common situations: 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.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/136329baa93bc652. Report an issue: GitHub.