zylon-ai/private-gpt · error · ValueError

Web Search is not properly initialized or is disabled in set

Error message

Web Search is not properly initialized or is disabled in settings.Consider enabling it in the configuration.

What it means

ValueError from WebSearchService.validate() when the service singleton never completed initialization. _initialize() returns early when settings.web_search.enabled is false (the default), leaving _initialized False; search() calls validate() first, so any search attempt fails immediately. Note validate() also chains to provider.validate() and processor.validate(), so after enabling the flag you may next hit the Brave key check.

Source

Thrown at private_gpt/components/web/web_search/web_search_service.py:73

        self._initialize_providers()
        self._initialize_processor()
        self._initialized = True

        logger.debug("WebSearchService initialized successfully")

    async def search(
        self, query: str, model_id: str | None = None, **kwargs: Any
    ) -> list[WebSearchResult]:
        await self.validate()

        provider_results: list[WebSearchResult] = await self._provider.make_query(
            query, self._settings.web_search.num_links, **kwargs
        )
        return await self._processor.process_results(query, provider_results, model_id)

    async def validate(self) -> None:
        if not self._initialized:
            raise ValueError(
                "Web Search is not properly initialized or is disabled in settings."
                "Consider enabling it in the configuration."
            )

        await self._provider.validate()
        await self._processor.validate()

    async def close(self) -> None:
        await self._provider.close()

    def _initialize_providers(self) -> None:
        if self._settings.web_search.provider == "brave":
            from private_gpt.components.web.web_search.providers.brave import (
                BraveSearchProvider,
            )

            self._provider = BraveSearchProvider(self._settings)
        elif self._settings.web_search.provider == "mock":

View on GitHub (pinned to 4a030776a3)

Solutions

Set web_search.enabled: true in the active settings profile (or PRIVATE_GPT_WEB_SEARCH_ENABLED=true).
Also configure what the chained validations need: brave.api_key and, for content processors, web_fetch.enabled.
Restart the process — the flag is read once at singleton construction.

Example fix

# settings.yaml
web_search:
  enabled: true   # was false/default
  provider: brave
  brave:
    api_key: "BSA..."

Defensive patterns

Strategy: validation

Validate before calling

svc = get_global_injector().get(WebSearchService)
await svc.validate()  # raises the exact config gap before user traffic hits it

Type guard

def web_search_initialized(svc: WebSearchService) -> bool:
    return svc._initialized

Try / catch

try:
    results = await search_svc.search(query)
except ValueError as e:
    if 'Web Search is not properly initialized' in str(e):
        raise RuntimeError('Enable web_search (and its brave key / web_fetch deps)') from e
    raise

Prevention

Call validate() in a readiness probe at startup.
Enable all three flags together: web_search.enabled, brave.api_key, web_fetch.enabled (for content processors).
Watch startup logs for 'Web Search is disabled in settings, skipping initialization'.

When it happens

Trigger: web_search.enabled left at default false while calling WebSearchService.search(); settings profile not loaded so the toggle never applied; startup log 'Web Search is disabled in settings, skipping initialization' preceding the failure.

Common situations: Expecting web search to work out of the box; enabling only web_fetch but not web_search; env var misnamed so the enabled override is ignored.

Related errors

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