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

Set BRAVE_SEARCH_API_KEY to a valid Brave Search API key in the environment the gateway runs in

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

Error message

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

What it means

The hosted web search feature selected the Brave provider, but no API key was found via the search environment resolution (BRAVE_SEARCH_API_KEY). The provider returns an empty result list rather than throwing, so searches silently yield nothing.

Source

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

    case "bing":
      return searchBing(input);
    case "google_cse":
      return searchGoogleCse(input);
    case "serper":
      return searchSerper(input);
    case "serpapi":
      return searchSerpApi(input);
    case "tavily":
      return searchTavily(input);
    case "exa":
      return searchExa(input);
  }
}

async function searchBrave(input: WebSearchProviderInput): Promise<WebSearchProviderResult[]> {
  const apiKey = searchEnv(input, "BRAVE_SEARCH_API_KEY");
  if (!apiKey) {
    console.warn("[gateway] Brave web search API key is not configured.");
    return [];
  }
  const url = new URL(searchEnv(input, "BRAVE_SEARCH_ENDPOINT") || "https://api.search.brave.com/res/v1/web/search");
  url.searchParams.set("q", input.query);
  url.searchParams.set("count", String(input.count));
  const raw = await fetchJson(url.toString(), {
    headers: { "x-subscription-token": apiKey },
    signal: AbortSignal.timeout(input.timeoutMs)
  });
  const items = isRecord(raw) && isRecord(raw.web) && Array.isArray(raw.web.results) ? raw.web.results : [];
  return items.map((item) => webSearchResult(item, "title", "url", "description")).filter(isWebSearchProviderResult);
}

async function searchBing(input: WebSearchProviderInput): Promise<WebSearchProviderResult[]> {
  const apiKey = searchEnv(input, "BING_SEARCH_API_KEY");
  if (!apiKey) {
    console.warn("[gateway] Bing web search API key is not configured.");
    return [];

View on GitHub (pinned to 99f24806c6)

Solutions

Set BRAVE_SEARCH_API_KEY to a valid Brave Search API key in the environment the gateway runs in
If using a custom key name, configure the provider env mapping so searchEnv resolves it
Restart the gateway process after adding the key to .env or service environment

Example fix

# before
# (no BRAVE_SEARCH_API_KEY set)
WEB_SEARCH_PROVIDER=brave

# after
BRAVE_SEARCH_API_KEY=BSA...
WEB_SEARCH_PROVIDER=brave

Defensive patterns

Strategy: validation

Validate before calling

if (!process.env.BRAVE_SEARCH_API_KEY) {
  throw new Error("BRAVE_SEARCH_API_KEY must be set before enabling the brave web search provider");
}

Prevention

Fail fast at startup when a provider is configured but its key is missing
Centralize env validation in a config loader
Add integration tests that assert non-empty provider results

When it happens

Trigger: Configuring web search provider to "brave" without setting BRAVE_SEARCH_API_KEY in the environment or provider-specific env config; the key being set in a different shell/process than the gateway runs in.

Common situations: .env file not loaded by the gateway process; key set only in interactive shell but gateway runs as a service/container; renaming or removing the env var after a config change.

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/99f25c6235cffc06. Report an issue: GitHub.