zylon-ai/private-gpt · error · ValueError

Brave Search API key is not configured

Error message

Brave Search API key is not configured

What it means

ValueError from BraveSearchProvider.validate(): the provider was constructed but settings.web_search.brave.api_key is None or whitespace-only. Validation runs from WebSearchService.search() → validate() before any HTTP call, so no request is wasted on a key that cannot authenticate.

Source

Thrown at private_gpt/components/web/web_search/providers/brave.py:81

        # 2. Make the request
        response_data = await self._execute_with_retry(
            query,
            num_links,
            offset,
            result_filter,
            safesearch,
            freshness,
            spellcheck,
            language,
        )

        # 3. Parser response
        return await asyncio.to_thread(self._parse_response, response_data)

    async def validate(self) -> None:
        if not self._api_key or not self._api_key.strip():
            raise ValueError("Brave Search API key is not configured")

    def _validate_query_params(
        self, query: str, num_links: int, offset: int
    ) -> tuple[str, int, int]:
        if not query or not query.strip():
            raise ValueError("Search query cannot be empty")

        normalized_num_links = max(1, min(20, num_links))  # Brave allows 1-20
        if normalized_num_links != num_links:
            logger.warning(
                f"Num_links {num_links} outside valid range [1,20], clamped to {normalized_num_links}"
            )

        if offset < 0:
            raise ValueError("Offset cannot be negative")

        return query, normalized_num_links, offset

View on GitHub (pinned to 4a030776a3)

Solutions

1. Set web_search.brave.api_key in settings (yaml or the corresponding env var).
2. Verify the env var is actually present in the process/container running private-gpt.
3. For local dev/tests, use provider: mock to avoid needing a key.

Example fix

# settings.yaml
web_search:
  enabled: true
  provider: brave
  brave:
    api_key: "BSA..."  # was missing/blank

key = settings.web_search.brave.api_key
if not key or not key.strip():
    raise ValueError('web_search.brave.api_key missing — set it before enabling brave')

try:
    results = await search_svc.search(query)
except ValueError as e:
    if 'Brave Search API key is not configured' in str(e):
        raise RuntimeError('Set web_search.brave.api_key in settings') from e
    raise

When it happens

Trigger: web_search.provider: brave (the default) with brave.api_key missing from settings; key set as empty string or containing only spaces; env var for the key not exported in the deployment environment.

Common situations: Enabling web search without signing up for a Brave Search API key; secrets managed in .env that are not passed to the container; key defined under the wrong YAML nesting (e.g. directly under web_search instead of web_search.brave).

Related errors

• Web fetching is not properly initialized or it is disabled.
• Web fetching is not properly initialized or it is disabled.
• Search query cannot be empty
• Brave Search API invalid token ({error_message})
• Web Search is not properly initialized or is disabled in set

AI-assisted analysis of zylon-ai/private-gpt@4a030776a3 (2026-08-15). Data as JSON: /api/errors/d6126e6cb690e182. Report an issue: GitHub.