open-webui/open-webui · error · ValueError

Invalid WEB_LOADER_ENGINE: {engine}. Please set it to 'safe_

Error message

Invalid WEB_LOADER_ENGINE: {engine}. Please set it to 'safe_web', 'playwright', 'firecrawl', 'tavily', 'external', or 'microsoft_web_iq'.

What it means

Raised by get_web_loader() in backend/open_webui/retrieval/web/utils.py when the WEB_LOADER_ENGINE setting does not resolve to any known loader class. The code maps engine names ('safe_web', 'playwright', 'firecrawl', 'tavily', 'external', 'microsoft_web_iq') to classes; an unrecognized name leaves WebLoaderClass falsy and the ValueError fires. It is purely a configuration-validation error, not a runtime/network failure.

Source

Thrown at backend/open_webui/retrieval/web/utils.py:973

                pass

    if engine == 'external':
        WebLoaderClass = ExternalWebLoader
        web_loader_args['external_url'] = cfg('external_web_loader_url', EXTERNAL_WEB_LOADER_URL)
        web_loader_args['external_api_key'] = cfg('external_web_loader_api_key', EXTERNAL_WEB_LOADER_API_KEY)

    if WebLoaderClass:
        web_loader = WebLoaderClass(**web_loader_args)

        log.debug(
            'Using WEB_LOADER_ENGINE %s for %s URLs',
            web_loader.__class__.__name__,
            len(safe_urls),
        )

        return web_loader
    else:
        raise ValueError(
            f'Invalid WEB_LOADER_ENGINE: {engine}. '
            "Please set it to 'safe_web', 'playwright', 'firecrawl', 'tavily', 'external', or 'microsoft_web_iq'."
        )

View on GitHub (pinned to 01f4282f1f)

Solutions

1. Set WEB_LOADER_ENGINE to one of the exact values listed in the message: 'safe_web', 'playwright', 'firecrawl', 'tavily', 'external', or 'microsoft_web_iq' (lowercase, no whitespace).
2. Restart the backend process/container after changing the env var so the config is re-read.
3. If using playwright/firecrawl/etc., verify the engine's optional dependency and its related API-key config (e.g. FIRECRAWL_API_KEY, PLAYWRIGHT install) are present, otherwise pick 'safe_web'.
4. Search the codebase for the engine->class mapping to confirm which names are compiled into your build.

Example fix

# before
WEB_LOADER_ENGINE=SafeWeb

# after
WEB_LOADER_ENGINE=safe_web

VALID_ENGINES = {'safe_web', 'playwright', 'firecrawl', 'tavily', 'external', 'microsoft_web_iq'}
engine = os.environ.get('WEB_LOADER_ENGINE', 'safe_web').strip().lower()
if engine not in VALID_ENGINES:
    raise SystemExit(f'WEB_LOADER_ENGINE must be one of {sorted(VALID_ENGINES)}, got {engine!r}')

When it happens

Trigger: Calling any web-search/RAG path that builds a web loader (e.g. the retrieval search pipeline) while the WEB_LOADER_ENGINE env/config value is misspelled ('SafeWeb', 'playwright ', 'chrome'), empty-but-set, or refers to an engine whose optional dependency is not installed so the class was never registered.

Common situations: Typos in .env / docker-compose environment variables; upgrading Open WebUI where an engine name was renamed or added; setting 'microsoft_web_iq' on a build missing its optional package; trailing whitespace or wrong casing in the env value.

Related errors

• Unknown embedding engine: {embedding_engine}
• distance_strategy must be 'cosine' or 'euclidean'
• Headers must be a valid JSON object
• Invalid scheme in CORS_ALLOW_ORIGIN: '{origin}'. Only 'http'
• Invalid URL structure in CORS_ALLOW_ORIGIN: '{origin}'.

AI-assisted analysis of open-webui/open-webui@01f4282f1f (2026-08-14). Data as JSON: /api/errors/193e39c54e2a7be8. Report an issue: GitHub.