{"record":{"id":"193e39c54e2a7be8","repo":"open-webui/open-webui","slug":"invalid-web-loader-engine-engine-please-set-it","errorCode":null,"errorMessage":"Invalid WEB_LOADER_ENGINE: {engine}. Please set it to 'safe_web', 'playwright', 'firecrawl', 'tavily', 'external', or 'microsoft_web_iq'.","messagePattern":"Invalid WEB_LOADER_ENGINE: (.+?)\\. Please set it to 'safe_web', 'playwright', 'firecrawl', 'tavily', 'external', or 'microsoft_web_iq'\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"backend/open_webui/retrieval/web/utils.py","lineNumber":973,"sourceCode":"                pass\n\n    if engine == 'external':\n        WebLoaderClass = ExternalWebLoader\n        web_loader_args['external_url'] = cfg('external_web_loader_url', EXTERNAL_WEB_LOADER_URL)\n        web_loader_args['external_api_key'] = cfg('external_web_loader_api_key', EXTERNAL_WEB_LOADER_API_KEY)\n\n    if WebLoaderClass:\n        web_loader = WebLoaderClass(**web_loader_args)\n\n        log.debug(\n            'Using WEB_LOADER_ENGINE %s for %s URLs',\n            web_loader.__class__.__name__,\n            len(safe_urls),\n        )\n\n        return web_loader\n    else:\n        raise ValueError(\n            f'Invalid WEB_LOADER_ENGINE: {engine}. '\n            \"Please set it to 'safe_web', 'playwright', 'firecrawl', 'tavily', 'external', or 'microsoft_web_iq'.\"\n        )\n","sourceCodeStart":955,"sourceCodeEnd":977,"githubUrl":"https://github.com/open-webui/open-webui/blob/01f4282f1ffe0d6212f58d3afbeae21fffd0c4be/backend/open_webui/retrieval/web/utils.py#L955-L977","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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).","Restart the backend process/container after changing the env var so the config is re-read.","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'.","Search the codebase for the engine->class mapping to confirm which names are compiled into your build."],"exampleFix":"# before\nWEB_LOADER_ENGINE=SafeWeb\n\n# after\nWEB_LOADER_ENGINE=safe_web","handlingStrategy":"validation","validationCode":"VALID_ENGINES = {'safe_web', 'playwright', 'firecrawl', 'tavily', 'external', 'microsoft_web_iq'}\nengine = os.environ.get('WEB_LOADER_ENGINE', 'safe_web').strip().lower()\nif engine not in VALID_ENGINES:\n    raise SystemExit(f'WEB_LOADER_ENGINE must be one of {sorted(VALID_ENGINES)}, got {engine!r}')","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Normalize the env value (strip/lowercase) at startup and fail fast with the valid-name list.","Add a startup config check that validates WEB_LOADER_ENGINE before serving traffic.","Pin engine names in CI config linting so renames surface at build time."],"tags":["configuration","web-loader","rag","validation"],"backgroundTag":null,"analyzedSha":"01f4282f1ffe0d6212f58d3afbeae21fffd0c4be","analyzedAt":"2026-08-14T18:25:22.715Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}