mastra-ai/mastra · error

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 contextualized embedding client requires a VoyageAI API key. At construction time it checks config.apiKey then the VOYAGE_API_KEY environment variable and throws immediately if neither is set — no network call is made.

Source

Thrown at embedders/voyageai/src/contextualized-embedding.ts:80

 * ```
 */
export class VoyageContextualizedEmbeddingModel {
  readonly provider = 'voyage' as const;
  readonly modelId: string;
  readonly maxEmbeddingsPerCall = 1000; // Max inputs
  readonly maxTotalChunks = 16000; // Max total chunks across all inputs
  readonly supportsParallelCalls = true;

  private client: VoyageAIClient;
  private config: VoyageContextualizedEmbeddingConfig;

  constructor(config: VoyageContextualizedEmbeddingConfig) {
    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 } : {}) });
  }

  /**
   * Generate contextualized embeddings for grouped chunks
   *
   * @param args.values - Nested array where each inner array contains chunks from the same document
   * @param args.inputType - 'query' for search queries, 'document' for content being indexed
   * @param args.outputDimension - Output embedding dimension (256, 512, 1024, or 2048)
   * @param args.outputDtype - Output data type
   * @param args.providerOptions - Runtime options to override config
   * @returns Object containing flattened embeddings array (one per chunk across all documents)
   */
  async doEmbed(args: {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass apiKey: process.env.VOYAGE_API_KEY or the literal key in the config object.
2. Export VOYAGE_API_KEY in your shell/CI before running the app.
3. Ensure your .env loader runs before the embedder is constructed.
4. Fix typos in the environment variable name.

Example fix

// before
const embedder = new VoyageContextualizedEmbedding({ model: 'voyage-context-3' });
// after
const embedder = new VoyageContextualizedEmbedding({
  model: 'voyage-context-3',
  apiKey: process.env.VOYAGE_API_KEY,
});

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

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

let embedder;
try {
  embedder = new VoyageContextualizedEmbedding(config);
} catch (err) {
  if ((err as Error).message.includes('API key is required')) {
    throw new Error('VoyageAI key missing: set VOYAGE_API_KEY in the environment or config');
  }
  throw err;
}

When it happens

Trigger: new VoyageContextualizedEmbedding({ model }) without apiKey in the config and no VOYAGE_API_KEY in the environment.

Common situations: Forgetting to set the env var in local dev, a CI secret not injected, .env file not loaded (e.g. dotenv not initialized before construction), or a typo like VOGAGE_API_KEY.

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

• VoyageAI API key is required. Set VOYAGE_API_KEY environment
• VoyageAI API key is required. Set VOYAGE_API_KEY environment
• VoyageAI API key is required. Set VOYAGE_API_KEY environment
• Need MOONSHOT_API_KEY
• Clerk JWKS URI, secret key and publishable key are required,

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