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 multimodal embedding client requires a VoyageAI API key, checked at construction from config.apiKey then VOYAGE_API_KEY. Missing both throws immediately before any API call.

Source

Thrown at embedders/voyageai/src/multimodal-embedding.ts:92

 * await vectorStore.upsert({ vectors: result.embeddings, ... });
 * ```
 */
export class VoyageMultimodalEmbeddingModel {
  readonly provider = 'voyage' as const;
  readonly modelId: string;
  readonly maxEmbeddingsPerCall = 1000;
  readonly supportsParallelCalls = true;

  private client: VoyageAIClient;
  private config: VoyageMultimodalEmbeddingConfig;

  constructor(config: VoyageMultimodalEmbeddingConfig) {
    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 embeddings for multimodal inputs
   *
   * @param args.values - Array of multimodal inputs, each containing interleaved content
   * @param args.providerOptions - Runtime options to override config
   * @returns Object containing embeddings array
   */
  async doEmbed(args: {
    values: VoyageMultimodalInput[];
    abortSignal?: AbortSignal;
    headers?: Record<string, string>;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass apiKey in the VoyageMultimodalEmbedding config.
2. Set VOYAGE_API_KEY in the environment before the process starts.
3. Load .env before instantiating the embedder.
4. Verify the variable name is spelled VOYAGE_API_KEY.

Example fix

// before
const embedder = new VoyageMultimodalEmbedding({ model: 'voyage-multimodal-3' });
// after
const embedder = new VoyageMultimodalEmbedding({
  model: 'voyage-multimodal-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 VoyageMultimodalEmbedding');
}
const embedder = new VoyageMultimodalEmbedding({ ...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 VoyageMultimodalEmbedding(config);
} catch (err) {
  if ((err as Error).message.includes('API key is required')) {
    throw new Error('VoyageAI key missing: check VOYAGE_API_KEY and deploy-time secrets');
  }
  throw err;
}

When it happens

Trigger: new VoyageMultimodalEmbedding({ model }) with no apiKey in config and VOYAGE_API_KEY unset in the environment.

Common situations: Missing env var in production containers, CI secrets not exposed to the deploy step, .env not loaded before construction, or key assigned to the wrong variable name.

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