MemPalace/mempalace · error · KeyError

unknown backend {name!r}; available: {available_backends()}

Error message

unknown backend {name!r}; available: {available_backends()}

What it means

Raised by get_backend_class() when the requested backend name is not in the registry after built-in and entry-point discovery. The message lists the sorted set of available backend names to make configuration mistakes immediately visible.

Source

Thrown at mempalace/backends/registry.py:106

                )
                continue
            _registry.setdefault(ep.name, cls)
        _discovered = True


def available_backends() -> list[str]:
    """Return sorted list of all registered backend names."""
    _discover_entry_points()
    return sorted(_registry.keys())


def get_backend_class(name: str) -> Type[BaseBackend]:
    """Return the registered backend class for ``name``."""
    _discover_entry_points()
    try:
        return _registry[name]
    except KeyError as e:
        raise KeyError(f"unknown backend {name!r}; available: {available_backends()}") from e


def get_backend(name: str) -> BaseBackend:
    """Return a long-lived instance of the named backend.

    Instances are cached per-name; repeated calls return the same object.
    Call :func:`reset_backends` in tests that need isolation.
    """
    _discover_entry_points()
    with _lock:
        inst = _instances.get(name)
        if inst is not None:
            return inst
        cls = _registry.get(name)
        if cls is None:
            raise KeyError(f"unknown backend {name!r}; available: {sorted(_registry.keys())}")
        inst = cls()
        _instances[name] = inst

View on GitHub (pinned to 06cb6987f0)

Solutions

1. Read the error message and use one of the listed available names
2. Install the optional extra that provides the backend (e.g. uv sync --extra qdrant / pip install 'mempalace[<backend>]')
3. Check spelling/case of the backend name in config
4. Upgrade mempalace if the backend was added in a newer version

Example fix

# before
cls = get_backend_class("Qdrant")  # KeyError: unknown backend 'Qdrant'
# after
cls = get_backend_class("qdrant")  # use exact lowercase name from available_backends()

from mempalace.backends.registry import available_backends

def safe_backend_class(name: str):
    if name not in available_backends():
        raise ValueError(f"backend {name!r} unavailable; installed: {available_backends()}")
    return get_backend_class(name)

def is_known_backend(name: str, known: list[str]) -> bool:
    return isinstance(name, str) and name in known

try:
    cls = get_backend_class(name)
except KeyError as e:
    log_and_list_available()  # message already enumerates available names
    raise

When it happens

Trigger: get_backend_class("qdrannt") (typo), get_backend_class("milvus") when the optional dependency providing it is not installed, or requesting a backend whose entry-point plugin failed to register.

Common situations: Typo'd MEMPALACE_BACKEND value; expecting a backend that ships as an extra (pip install mempalace[milvus]) that was not installed; plugin package present but its entry point metadata broken; older mempalace version lacking a newer backend.

Related errors

• unknown backend {name!r}; available: {sorted(_registry.keys(
• ChromaBackend requires PalaceRef.local_path
• {palace_path}
• Embedding model mismatch reading palace at {palace_path!r}.
• milvus_consistency_level must be one of: {allowed}

AI-assisted analysis of MemPalace/mempalace@06cb6987f0 (2026-08-15). Data as JSON: /api/errors/042fdcbf1a81e227. Report an issue: GitHub.