{"record":{"id":"aacafda26a5f7727","repo":"mastra-ai/mastra","slug":"voyageai-api-key-is-required-set-voyage-api-key-e-aacafd","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/text-embedding.ts","lineNumber":84,"sourceCode":"export class VoyageTextEmbeddingModelV2 {\n  readonly specificationVersion = 'v2' as const;\n  readonly provider = 'voyage' as const;\n  readonly modelId: string;\n  readonly maxEmbeddingsPerCall = 1000; // VoyageAI supports up to 1000 inputs per API call\n  readonly supportsParallelCalls = true;\n\n  private client: VoyageAIClient;\n  private config: VoyageTextEmbeddingConfig;\n  private maxInputTokens: number;\n\n  constructor(config: VoyageTextEmbeddingConfig) {\n    this.modelId = config.model;\n    this.config = config;\n    this.maxInputTokens = TEXT_MODEL_INFO[config.model]?.maxInputTokens ?? 32000;\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   * Generate embeddings for the provided text values.\n   * Automatically splits inputs into token-aware batches when total tokens\n   * would exceed the model's limit.\n   */\n  async doEmbed(args: {\n    values: string[];\n    abortSignal?: AbortSignal;\n    headers?: Record<string, string>;\n    providerOptions?: VoyageProviderOptions;\n  }): Promise<{ embeddings: number[][] }> {","sourceCodeStart":66,"sourceCodeEnd":102,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/embedders/voyageai/src/text-embedding.ts#L66-L102","documentation":"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.","triggerScenarios":"new VoyageEmbedding({ model }) with no apiKey in config and VOYAGE_API_KEY unset in the environment.","commonSituations":"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).","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."],"exampleFix":"// before\nconst embedder = new VoyageEmbedding({ model: 'voyage-3' });\n// after\nconst embedder = new VoyageEmbedding({\n  model: 'voyage-3',\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 VoyageEmbedding');\n}\nconst embedder = new VoyageEmbedding({ ...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 embedder;\ntry {\n  embedder = new VoyageEmbedding(config);\n} catch (err) {\n  if ((err as Error).message.includes('API key is required')) {\n    throw new Error('VoyageAI key missing: export VOYAGE_API_KEY or pass apiKey in config');\n  }\n  throw err;\n}","preventionTips":["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."],"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"}