{"record":{"id":"76925ff8dec11ff5","repo":"unslothai/unsloth","slug":"unknown-rag-embed-backend-config-embed-backend-r","errorCode":null,"errorMessage":"Unknown RAG_EMBED_BACKEND={config.EMBED_BACKEND!r}; expected 'auto', 'sentence-transformers' or 'llama-server'","messagePattern":"Unknown RAG_EMBED_BACKEND=(.+?); expected 'auto', 'sentence-transformers' or 'llama-server'","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"studio/backend/core/rag/embeddings.py","lineNumber":666,"sourceCode":"\ndef _get_backend():\n    \"\"\"The process-wide embedding backend for ``config.EMBED_BACKEND``, built once.\n    Cached by the raw config value, so ``auto`` detection runs only on a miss and a\n    config change rebuilds it.\"\"\"\n    global _backend, _backend_key\n    raw = (config.EMBED_BACKEND or \"auto\").strip().lower()\n    with _backend_lock:\n        if _backend is not None and _backend_key == raw:\n            return _backend\n        key = _resolve_auto() if raw in _AUTO_ALIASES else raw\n        if key in _ST_ALIASES:\n            _backend = _build_st_backend_or_fallback()\n        elif key in _LLAMA_ALIASES:\n            # Imported lazily so the ST path never imports llama plumbing.\n            from .embed_llama_server import LlamaServerBackend\n            _backend = LlamaServerBackend()\n        else:\n            raise ValueError(\n                f\"Unknown RAG_EMBED_BACKEND={config.EMBED_BACKEND!r}; expected \"\n                \"'auto', 'sentence-transformers' or 'llama-server'\"\n            )\n        _backend_key = raw\n        return _backend\n\n\ndef _reset_backend() -> None:\n    \"\"\"Drop the cached backend (test teardown / re-init).\"\"\"\n    global _backend, _backend_key\n    with _backend_lock:\n        _backend = None\n        _backend_key = None\n\n\ndef active_backend_is_llama() -> bool:\n    \"\"\"True when this process actually embeds via the llama-server (GGUF) backend.\n","sourceCodeStart":648,"sourceCodeEnd":684,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/rag/embeddings.py#L648-L684","documentation":"ValueError raised when resolving the embedding backend: config.EMBED_BACKEND (env RAG_EMBED_BACKEND), after strip/lower, matches neither the 'auto' aliases, the sentence-transformers aliases, nor the llama-server aliases. This is a pure configuration-validation error raised before any backend is constructed; the accepted values are 'auto', 'sentence-transformers', and 'llama-server' (plus their aliases).","triggerScenarios":"Setting RAG_EMBED_BACKEND to a typo ('sentencetransformers'), an unsupported backend name ('openai', 'ollama'), or leaving stray characters/quotes in the env var; calling get_backend() after config was loaded from a stale .env with the old value format.","commonSituations":"Copying config from tutorials that reference backends this build does not ship; renaming a backend in a newer version and running an old .env; whitespace or CRLF artifacts in Windows env files.","solutions":["Set RAG_EMBED_BACKEND to one of 'auto' (default), 'sentence-transformers', or 'llama-server'.","Check for typos, trailing whitespace, quotes, or CR characters in the env var / config file.","Unset the variable entirely to use 'auto'.","Search the codebase for _ST_ALIASES/_LLAMA_ALIASES to see the exact accepted spellings for your version."],"exampleFix":"# before\nRAG_EMBED_BACKEND=sentencetransformer  # typo, unknown\n\n# after\nRAG_EMBED_BACKEND=sentence-transformers","handlingStrategy":"validation","validationCode":"_VALID_BACKENDS = {\"auto\", \"sentence-transformers\", \"llama-server\"}\n\ndef backend_config_ok(raw: str | None) -> bool:\n    return (raw or \"auto\").strip().lower() in _VALID_BACKENDS","typeGuard":null,"tryCatchPattern":"try:\n    backend = get_backend()\nexcept ValueError as e:\n    if \"Unknown RAG_EMBED_BACKEND\" not in str(e):\n        raise\n    os.environ[\"RAG_EMBED_BACKEND\"] = \"auto\"\n    backend = get_backend()","preventionTips":["Validate RAG_EMBED_BACKEND at config-load time against the accepted set, not at first backend use.","Document the exact accepted spellings next to the env var in your deployment README.","Fail fast on app boot for unknown config values so typos surface before ingestion starts."],"tags":["configuration","env-vars","embeddings","validation"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}