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 text embedding client requires a VoyageAI API key, validated in the constructor from config.apiKey or VOYAGE_API_KEY. Missing both throws immediately, before any embedding request is made.

Source

Thrown at embedders/voyageai/src/text-embedding.ts:84

export class VoyageTextEmbeddingModelV2 {
  readonly specificationVersion = 'v2' as const;
  readonly provider = 'voyage' as const;
  readonly modelId: string;
  readonly maxEmbeddingsPerCall = 1000; // VoyageAI supports up to 1000 inputs per API call
  readonly supportsParallelCalls = true;

  private client: VoyageAIClient;
  private config: VoyageTextEmbeddingConfig;
  private maxInputTokens: number;

  constructor(config: VoyageTextEmbeddingConfig) {
    this.modelId = config.model;
    this.config = config;
    this.maxInputTokens = TEXT_MODEL_INFO[config.model]?.maxInputTokens ?? 32000;

    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 the provided text values.
   * Automatically splits inputs into token-aware batches when total tokens
   * would exceed the model's limit.
   */
  async doEmbed(args: {
    values: string[];
    abortSignal?: AbortSignal;
    headers?: Record<string, string>;
    providerOptions?: VoyageProviderOptions;
  }): Promise<{ embeddings: number[][] }> {

View on GitHub (pinned to 75dd419e61)

Solutions

Pass apiKey in the embedding config.
Set VOYAGE_API_KEY in the environment or hosting platform secrets.
Load .env before constructing the embedder.
Verify the variable name is exactly VOYAGE_API_KEY and non-empty.

Example fix

// before
const embedder = new VoyageEmbedding({ model: 'voyage-3' });
// after
const embedder = new VoyageEmbedding({
  model: 'voyage-3',
  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 VoyageEmbedding');
}
const embedder = new VoyageEmbedding({ ...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 embedder;
try {
  embedder = new VoyageEmbedding(config);
} catch (err) {
  if ((err as Error).message.includes('API key is required')) {
    throw new Error('VoyageAI key missing: export VOYAGE_API_KEY or pass apiKey in config');
  }
  throw err;
}

Prevention

Set VOYAGE_API_KEY in every environment the app runs in (dev, CI, prod).
Initialize dotenv/config loading before the first Voyage client import or instantiation.
Assert key presence during app bootstrap.
Use exact variable name VOYAGE_API_KEY; avoid near-miss names.

When it happens

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

Common situations: Deploying without the secret configured, switching machines without the shell export, .env loaded after construction, or naming the variable MISTRAL/OPENAI-style (e.g. VOYAGE_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

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