Tavily API key is required. Pass { apiKey } or set TAVILY_AP

Error message

Tavily API key is required. Pass { apiKey } or set TAVILY_API_KEY env var.

What it means

getTavilyClient resolves the API key from config or the TAVILY_API_KEY env var and throws if neither is set, because all Tavily API calls require authentication.

Source

Thrown at integrations/tavily/src/client.ts:11

import { tavily } from '@tavily/core';
import type { TavilyClientOptions } from '@tavily/core';

export type { TavilyClientOptions };

export type TavilyClient = ReturnType<typeof tavily>;

export function getTavilyClient(config?: TavilyClientOptions): TavilyClient {
  const apiKey = config?.apiKey ?? process.env.TAVILY_API_KEY;
  if (!apiKey) {
    throw new Error('Tavily API key is required. Pass { apiKey } or set TAVILY_API_KEY env var.');
  }
  // defaulting `clientName` to `mastra` if not provided
  return tavily({ ...config, apiKey, clientName: config?.clientName ?? 'mastra' });
}

View on GitHub (pinned to 75dd419e61)

Solutions

Set TAVILY_API_KEY in the environment.
Pass { apiKey } explicitly to getTavilyClient (e.g. from a secrets manager).
Ensure .env loading happens before the first getTavilyClient call.

Example fix

// before
const tavily = getTavilyClient();
// after
const tavily = getTavilyClient({ apiKey: process.env.TAVILY_API_KEY! });

Defensive patterns

Strategy: validation

Validate before calling

const apiKey = config?.apiKey ?? process.env.TAVILY_API_KEY;
if (!apiKey) throw new Error('Set TAVILY_API_KEY before creating the Tavily client');

Type guard

function hasTavilyApiKey(config?: { apiKey?: string }): boolean {
  return typeof config?.apiKey === 'string' && config.apiKey.length > 0 || !!process.env.TAVILY_API_KEY;
}

Try / catch

try {
  const tavily = getTavilyClient();
} catch (e) {
  if ((e as Error).message.includes('Tavily API key is required')) {
    throw new Error('TAVILY_API_KEY not configured in this environment');
  }
  throw e;
}

Prevention

Load .env before client creation and assert TAVILY_API_KEY at boot
Add TAVILY_API_KEY to serverless/CI environment configuration
Prefer explicit { apiKey } injection from a secrets manager in production

When it happens

Trigger: Calling getTavilyClient() or any tool/factory that calls it (client, getClient) with no config.apiKey while process.env.TAVILY_API_KEY is undefined.

Common situations: Missing .env or dotenv not invoked before client creation; key configured under a different var name; serverless deploy where env vars weren't attached to the function.

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

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