Graphify-Labs/graphify · error · ValueError

Unknown backend {backend!r}. Available: {sorted(BACKENDS)}

Error message

Unknown backend {backend!r}. Available: {sorted(BACKENDS)}

What it means

Raised by `extract_files_direct` when the supplied `backend` string is not a key in the `BACKENDS` registry. The message lists all valid names (`sorted(BACKENDS)`), e.g. gemini, claude, claude-cli, openai, kimi, deepseek, moonshot, azure, bedrock, ollama. It guards the dispatch chain (if backend == "claude" elif ...) from falling through silently.

Source

Thrown at graphify/llm.py:1768

    Accepts ``str`` paths as well as ``Path``; string entries are coerced up
    front so downstream helpers (``_partition_semantic_files``, ``_read_files``,
    ``_build_image_refs``) can rely on ``Path`` semantics (#1386). FileSlice units
    (from extract_corpus_parallel's oversized-doc slicing, #1369) pass through
    untouched — Path(FileSlice) would raise (#1397/#1399).
    """
    files = [f if isinstance(f, (Path, FileSlice)) else Path(f) for f in files]
    if backend is None:
        backend = detect_backend()
        if backend is None:
            raise ValueError(
                "No LLM backend configured. Set one of: GEMINI_API_KEY, ANTHROPIC_API_KEY, "
                "OPENAI_API_KEY, DEEPSEEK_API_KEY, MOONSHOT_API_KEY, "
                "AZURE_OPENAI_API_KEY+AZURE_OPENAI_ENDPOINT, OLLAMA_BASE_URL, "
                "or AWS credentials. Pass backend= explicitly to select a provider."
            )
    if backend not in BACKENDS:
        raise ValueError(f"Unknown backend {backend!r}. Available: {sorted(BACKENDS)}")

    cfg = BACKENDS[backend]
    key = api_key or _get_backend_api_key(backend)
    if not key and backend == "ollama":
        # Ollama ignores auth but the OpenAI client library requires a non-empty
        # string. Use a placeholder and surface a visible warning so this never
        # silently routes traffic without the user realising — see F-029.
        ollama_url = _resolve_ollama_base_url(cfg.get("base_url", ""))
        _validate_ollama_base_url(ollama_url)
        print(
            "[graphify] WARNING: ollama backend selected with no OLLAMA_API_KEY set; "
            f"sending corpus to {ollama_url}. Set OLLAMA_API_KEY (any non-empty value) "
            "to suppress this warning.",
            file=sys.stderr,
        )
        key = "ollama"
    if not key and backend not in ("bedrock", "claude-cli"):
        raise ValueError(

View on GitHub (pinned to 7fe58b0b0f)

Solutions

  1. Use one of the names printed in the message's `Available: [...]` list, exactly and lowercase.
  2. For custom OpenAI-compatible endpoints, check whether the installed version supports an override (e.g. base_url configuration under a registered backend name) rather than inventing a backend string.
  3. Upgrade graphify if the docs mention a backend your install doesn't list.

Example fix

# before
extract_files_direct(files, root, backend="GPT4")

# after
extract_files_direct(files, root, backend="openai")
Defensive patterns

Strategy: type-guard

Type guard

from graphify.llm import BACKENDS

def is_known_backend(name: str) -> bool:
    """True when name is a registered graphify backend (case-sensitive)."""
    return isinstance(name, str) and name in BACKENDS

assert is_known_backend(user_backend), f"pick from {sorted(BACKENDS)}"

Prevention

When it happens

Trigger: Passing a misspelled or unsupported backend: `backend="gpt4"`, `backend="Claude"` (case-sensitive), `backend="openai-compatible"`, or a provider added in a newer graphify version used against an older install.

Common situations: Typos and casing mistakes; assuming an arbitrary provider name works because the API is 'OpenAI-compatible' (must use a registered backend name); version skew between docs and installed package.

Related errors

AI-assisted analysis of Graphify-Labs/graphify@7fe58b0b0f (2026-08-14). Data as JSON: /api/errors/73e446f979e9e36d. Report an issue: GitHub.