unslothai/unsloth · error · ValueError

Unknown RAG_EMBED_BACKEND={config.EMBED_BACKEND!r}; expected

Error message

Unknown RAG_EMBED_BACKEND={config.EMBED_BACKEND!r}; expected 'auto', 'sentence-transformers' or 'llama-server'

What it means

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).

Source

Thrown at studio/backend/core/rag/embeddings.py:666

def _get_backend():
    """The process-wide embedding backend for ``config.EMBED_BACKEND``, built once.
    Cached by the raw config value, so ``auto`` detection runs only on a miss and a
    config change rebuilds it."""
    global _backend, _backend_key
    raw = (config.EMBED_BACKEND or "auto").strip().lower()
    with _backend_lock:
        if _backend is not None and _backend_key == raw:
            return _backend
        key = _resolve_auto() if raw in _AUTO_ALIASES else raw
        if key in _ST_ALIASES:
            _backend = _build_st_backend_or_fallback()
        elif key in _LLAMA_ALIASES:
            # Imported lazily so the ST path never imports llama plumbing.
            from .embed_llama_server import LlamaServerBackend
            _backend = LlamaServerBackend()
        else:
            raise ValueError(
                f"Unknown RAG_EMBED_BACKEND={config.EMBED_BACKEND!r}; expected "
                "'auto', 'sentence-transformers' or 'llama-server'"
            )
        _backend_key = raw
        return _backend


def _reset_backend() -> None:
    """Drop the cached backend (test teardown / re-init)."""
    global _backend, _backend_key
    with _backend_lock:
        _backend = None
        _backend_key = None


def active_backend_is_llama() -> bool:
    """True when this process actually embeds via the llama-server (GGUF) backend.

View on GitHub (pinned to 203007d190)

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.

Example fix

# before
RAG_EMBED_BACKEND=sentencetransformer  # typo, unknown

# after
RAG_EMBED_BACKEND=sentence-transformers

Defensive patterns

Strategy: validation

Validate before calling

_VALID_BACKENDS = {"auto", "sentence-transformers", "llama-server"}

def backend_config_ok(raw: str | None) -> bool:
    return (raw or "auto").strip().lower() in _VALID_BACKENDS

Try / catch

try:
    backend = get_backend()
except ValueError as e:
    if "Unknown RAG_EMBED_BACKEND" not in str(e):
        raise
    os.environ["RAG_EMBED_BACKEND"] = "auto"
    backend = get_backend()

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/76925ff8dec11ff5. Report an issue: GitHub.