{"record":{"id":"e6ac988c4ac4888a","repo":"mastra-ai/mastra","slug":"voyageai-api-key-is-required-set-voyage-api-key-e","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/contextualized-embedding.ts","lineNumber":80,"sourceCode":" * ```\n */\nexport class VoyageContextualizedEmbeddingModel {\n  readonly provider = 'voyage' as const;\n  readonly modelId: string;\n  readonly maxEmbeddingsPerCall = 1000; // Max inputs\n  readonly maxTotalChunks = 16000; // Max total chunks across all inputs\n  readonly supportsParallelCalls = true;\n\n  private client: VoyageAIClient;\n  private config: VoyageContextualizedEmbeddingConfig;\n\n  constructor(config: VoyageContextualizedEmbeddingConfig) {\n    this.modelId = config.model;\n    this.config = config;\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 contextualized embeddings for grouped chunks\n   *\n   * @param args.values - Nested array where each inner array contains chunks from the same document\n   * @param args.inputType - 'query' for search queries, 'document' for content being indexed\n   * @param args.outputDimension - Output embedding dimension (256, 512, 1024, or 2048)\n   * @param args.outputDtype - Output data type\n   * @param args.providerOptions - Runtime options to override config\n   * @returns Object containing flattened embeddings array (one per chunk across all documents)\n   */\n  async doEmbed(args: {","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/embedders/voyageai/src/contextualized-embedding.ts#L62-L98","documentation":"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.","triggerScenarios":"new VoyageContextualizedEmbedding({ model }) without apiKey in the config and no VOYAGE_API_KEY in the environment.","commonSituations":"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.","solutions":["Pass apiKey: process.env.VOYAGE_API_KEY or the literal key in the config object.","Export VOYAGE_API_KEY in your shell/CI before running the app.","Ensure your .env loader runs before the embedder is constructed.","Fix typos in the environment variable name."],"exampleFix":"// before\nconst embedder = new VoyageContextualizedEmbedding({ model: 'voyage-context-3' });\n// after\nconst embedder = new VoyageContextualizedEmbedding({\n  model: 'voyage-context-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 VoyageContextualizedEmbedding');\n}\nconst embedder = new VoyageContextualizedEmbedding({ ...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 VoyageContextualizedEmbedding(config);\n} catch (err) {\n  if ((err as Error).message.includes('API key is required')) {\n    throw new Error('VoyageAI key missing: set VOYAGE_API_KEY in the environment or config');\n  }\n  throw err;\n}","preventionTips":["Set VOYAGE_API_KEY in .env, shell profile, and CI/secrets.","Load dotenv before constructing any Voyage client.","Assert the key exists at app startup (fail fast).","Pass apiKey explicitly from config rather than relying on ambient env."],"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"}