sgl-project/sglang · error · ValueError

Unknown serve backend {name!r}. Available values: {available

Error message

Unknown serve backend {name!r}. Available values: {available}.

What it means

Raised by ServeBackendRegistry.get() when the requested backend name has no matching entry point in the 'sglang.serve_backends' registry group. The CLI resolves backends via Python entry points, so a typo or an uninstalled provider package yields this ValueError. The message lists 'auto' plus all registered backend names.

Source

Thrown at python/sglang/cli/serve_backends.py:128

        return discovered

    @property
    def available_names(self) -> tuple[str, ...]:
        """Return backend names without importing out-of-tree packages."""

        external_names = sorted(set(self._entry_points) - set(self._builtins))
        return (*self._builtins, *external_names)

    def get(self, name: str) -> RegisteredServeBackend:
        """Return one backend, importing only the explicitly requested plugin."""

        if name in self._loaded:
            return self._loaded[name]

        candidates = self._entry_points.get(name, [])
        if not candidates:
            available = ", ".join(("auto", *self.available_names))
            raise ValueError(
                f"Unknown serve backend {name!r}. Available values: {available}."
            )
        if len(candidates) > 1:
            providers = ", ".join(
                sorted(
                    self._entry_point_provider(candidate) for candidate in candidates
                )
            )
            raise RuntimeError(
                f"Multiple distributions register serve backend {name!r}: "
                f"{providers}. Uninstall one provider or choose another backend name."
            )

        entry_point = candidates[0]
        try:
            factory = entry_point.load()
            if not callable(factory):
                raise TypeError("the entry point must resolve to a callable factory")

View on GitHub (pinned to 0132848349)

Solutions

Re-run with a name from the message's available list (or omit --model-type to use auto detection).
Fix the typo in --model-type / the name passed to get().
Verify the provider package is installed and exposes an entry point under the 'sglang.serve_backends' group: `pip show <pkg>` and inspect its dist-info entry_points.txt.
If developing a backend, register it via pyproject [project.entry-points.'sglang.serve_backends'] and reinstall.

Example fix

# before
sglang serve --model-path model --model-type difusion
# after
sglang serve --model-path model --model-type diffusion

Defensive patterns

Strategy: validation

Validate before calling

from sglang.cli.serve_backends import ServeBackendRegistry
reg = ServeBackendRegistry()
if name not in reg.available_names and name != "auto":
    raise SystemExit(f"pick one of: auto, {reg.available_names}")
backend = reg.get(name)

Type guard

def is_valid_backend(reg, name: str) -> bool:
    return name == "auto" or name in reg.available_names

Try / catch

try:
    backend = registry.get(name)
except ValueError as e:
    if "Unknown serve backend" in str(e):
        print(f"invalid backend; available: {registry.available_names}")
    raise

Prevention

List available backends (registry.available_names) before accepting user input for --model-type.
Validate backend names at CLI-arg parse time rather than deep in registry.get().
Pin provider packages in requirements so expected backends are always installed.

When it happens

Trigger: Calling sglang serve --model-type <name> with a name not in registry.available_names; calling registry.get(name) programmatically with a misspelled or unregistered backend; a provider package whose entry points were not installed (pip install -e without regenerating metadata).

Common situations: Typo in --model-type (e.g. 'difusion' vs 'diffusion'); expecting a backend from a plugin package that isn't installed in the current venv; stale environment after switching branches of a provider package.

Related errors

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/35296e59ba3aa7e7. Report an issue: GitHub.