What causes "[gateway] Exa web search API key is not configured." in musistudio/claude-code-router?

Set EXA_API_KEY in the gateway's environment

[gateway] Exa web search API key is not configured.

Error message

[gateway] Exa web search API key is not configured.

What it means

The Exa.ai web search provider was selected, but EXA_API_KEY is not configured in the resolved environment. The provider returns empty results, so search-backed features degrade to no results without failing.

Source

Thrown at packages/core/src/gateway/features/hosted-web-search/discovery.ts:649

  const raw = await fetchJson(searchEnv(input, "TAVILY_SEARCH_ENDPOINT") || "https://api.tavily.com/search", {
    body: JSON.stringify({
      api_key: apiKey,
      max_results: input.count,
      query: input.query,
      search_depth: "basic"
    }),
    headers: { "content-type": "application/json" },
    method: "POST",
    signal: AbortSignal.timeout(input.timeoutMs)
  });
  const items = isRecord(raw) && Array.isArray(raw.results) ? raw.results : [];
  return items.map((item) => webSearchResult(item, "title", "url", "content")).filter(isWebSearchProviderResult);
}

async function searchExa(input: WebSearchProviderInput): Promise<WebSearchProviderResult[]> {
  const apiKey = searchEnv(input, "EXA_API_KEY");
  if (!apiKey) {
    console.warn("[gateway] Exa web search API key is not configured.");
    return [];
  }
  const raw = await fetchJson(searchEnv(input, "EXA_SEARCH_ENDPOINT") || "https://api.exa.ai/search", {
    body: JSON.stringify({
      numResults: input.count,
      query: input.query
    }),
    headers: {
      authorization: `Bearer ${apiKey}`,
      "content-type": "application/json"
    },
    method: "POST",
    signal: AbortSignal.timeout(input.timeoutMs)
  });
  const items = isRecord(raw) && Array.isArray(raw.results) ? raw.results : [];
  return items.map((item) => webSearchResult(item, "title", "url", "text")).filter(isWebSearchProviderResult);
}

View on GitHub (pinned to 99f24806c6)

Solutions

Set EXA_API_KEY in the gateway's environment
Verify the key with a direct curl to https://api.exa.ai/search
Restart the gateway

Example fix

# before
WEB_SEARCH_PROVIDER=exa

# after
EXA_API_KEY=<exa-key>
WEB_SEARCH_PROVIDER=exa

Defensive patterns

Strategy: validation

Validate before calling

if (!process.env.EXA_API_KEY) throw new Error("EXA_API_KEY required for exa provider");

Prevention

Validate keys at startup
Keep provider key config in one audited place
Dry-run the provider with a one-off query after setup

When it happens

Trigger: Configuring web search provider to "exa" without EXA_API_KEY; key set in CI secrets but not in the runtime deployment.

Common situations: Key from exa.ai dashboard never exported; container missing env; gateway service restarted without the secret.

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 musistudio/claude-code-router@99f24806c6 (2026-08-27). Data as JSON: /api/errors/b37fdd4aeafbd8cb. Report an issue: GitHub.