sgl-project/sglang · critical · RuntimeError

Serve backend {name!r} uses API version {backend.api_version

Error message

Serve backend {name!r} uses API version {backend.api_version}; this SGLang release requires version {SERVE_BACKEND_API_VERSION}.

What it means

The loaded backend reports an api_version that differs from SERVE_BACKEND_API_VERSION required by the installed SGLang release. This is an explicit ABI/contract version gate so mismatched plugin binaries fail fast with a clear message instead of crashing mid-serve.

Source

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

        entry_point = candidates[0]
        try:
            factory = entry_point.load()
            if not callable(factory):
                raise TypeError("the entry point must resolve to a callable factory")
            backend = factory()
        except Exception as exc:
            raise RuntimeError(
                f"Failed to load serve backend {name!r} from "
                f"{self._entry_point_provider(entry_point)}: {exc}"
            ) from exc

        if not isinstance(backend, ServeBackend):
            raise TypeError(
                f"Serve backend {name!r} factory returned {type(backend).__name__}; "
                "expected sglang.cli.serve_backends.ServeBackend."
            )
        if backend.api_version != SERVE_BACKEND_API_VERSION:
            raise RuntimeError(
                f"Serve backend {name!r} uses API version {backend.api_version}; "
                f"this SGLang release requires version {SERVE_BACKEND_API_VERSION}."
            )

        registered = RegisteredServeBackend(
            name=name,
            backend=backend,
            distribution=self._entry_point_distribution(entry_point),
        )
        self._loaded[name] = registered
        return registered

    def auto_detect(self, request: ServeRequest) -> RegisteredServeBackend:
        """Resolve a unique detector match, falling back to the ``llm`` backend."""

        matches: list[RegisteredServeBackend] = []
        for name in self.available_names:
            if name == "llm":

View on GitHub (pinned to 0132848349)

Solutions

  1. Upgrade the provider package to a release matching your sglang version.
  2. Or downgrade sglang to the version the plugin was built for.
  3. If you own the plugin, set its api_version to SERVE_BACKEND_API_VERSION from the target sglang and adapt to any interface changes.

Example fix

# before (plugin)
class MyBackend(ServeBackend):
    api_version = 1  # sglang now requires 2
# after
from sglang.cli.serve_backends import SERVE_BACKEND_API_VERSION
class MyBackend(ServeBackend):
    api_version = SERVE_BACKEND_API_VERSION
Defensive patterns

Strategy: validation

Validate before calling

from sglang.cli.serve_backends import SERVE_BACKEND_API_VERSION, ServeBackendRegistry
b = ServeBackendRegistry().get(name)  # raises if mismatched
# plugin-side: assert at import time
assert MyBackend.api_version == SERVE_BACKEND_API_VERSION

Type guard

from sglang.cli.serve_backends import SERVE_BACKEND_API_VERSION

def backend_api_compatible(backend) -> bool:
    return getattr(backend, "api_version", None) == SERVE_BACKEND_API_VERSION

Try / catch

try:
    backend = registry.get(name)
except RuntimeError as e:
    if "API version" in str(e):
        print("upgrade the plugin package to match this sglang release")
        raise

Prevention

When it happens

Trigger: A plugin built for an older/newer SGLang backend API is installed; sglang was upgraded (bumping SERVE_BACKEND_API_VERSION) but the plugin package was not; calling registry.get(name) on such a plugin.

Common situations: pip install -U sglang without upgrading companion plugin packages; using a nightly sglang with plugins pinned to a release; developing a plugin against a different checkout.

Related errors

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