{"record":{"id":"8dc013916b84e654","repo":"sgl-project/sglang","slug":"serve-backend-name-r-uses-api-version-backend-a","errorCode":null,"errorMessage":"Serve backend {name!r} uses API version {backend.api_version}; this SGLang release requires version {SERVE_BACKEND_API_VERSION}.","messagePattern":"Serve backend (.+?) uses API version (.+?); this SGLang release requires version (.+?)\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"python/sglang/cli/serve_backends.py","lineNumber":160,"sourceCode":"        entry_point = candidates[0]\n        try:\n            factory = entry_point.load()\n            if not callable(factory):\n                raise TypeError(\"the entry point must resolve to a callable factory\")\n            backend = factory()\n        except Exception as exc:\n            raise RuntimeError(\n                f\"Failed to load serve backend {name!r} from \"\n                f\"{self._entry_point_provider(entry_point)}: {exc}\"\n            ) from exc\n\n        if not isinstance(backend, ServeBackend):\n            raise TypeError(\n                f\"Serve backend {name!r} factory returned {type(backend).__name__}; \"\n                \"expected sglang.cli.serve_backends.ServeBackend.\"\n            )\n        if backend.api_version != SERVE_BACKEND_API_VERSION:\n            raise RuntimeError(\n                f\"Serve backend {name!r} uses API version {backend.api_version}; \"\n                f\"this SGLang release requires version {SERVE_BACKEND_API_VERSION}.\"\n            )\n\n        registered = RegisteredServeBackend(\n            name=name,\n            backend=backend,\n            distribution=self._entry_point_distribution(entry_point),\n        )\n        self._loaded[name] = registered\n        return registered\n\n    def auto_detect(self, request: ServeRequest) -> RegisteredServeBackend:\n        \"\"\"Resolve a unique detector match, falling back to the ``llm`` backend.\"\"\"\n\n        matches: list[RegisteredServeBackend] = []\n        for name in self.available_names:\n            if name == \"llm\":","sourceCodeStart":142,"sourceCodeEnd":178,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/cli/serve_backends.py#L142-L178","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Upgrade the provider package to a release matching your sglang version.","Or downgrade sglang to the version the plugin was built for.","If you own the plugin, set its api_version to SERVE_BACKEND_API_VERSION from the target sglang and adapt to any interface changes."],"exampleFix":"# before (plugin)\nclass MyBackend(ServeBackend):\n    api_version = 1  # sglang now requires 2\n# after\nfrom sglang.cli.serve_backends import SERVE_BACKEND_API_VERSION\nclass MyBackend(ServeBackend):\n    api_version = SERVE_BACKEND_API_VERSION","handlingStrategy":"validation","validationCode":"from sglang.cli.serve_backends import SERVE_BACKEND_API_VERSION, ServeBackendRegistry\nb = ServeBackendRegistry().get(name)  # raises if mismatched\n# plugin-side: assert at import time\nassert MyBackend.api_version == SERVE_BACKEND_API_VERSION","typeGuard":"from sglang.cli.serve_backends import SERVE_BACKEND_API_VERSION\n\ndef backend_api_compatible(backend) -> bool:\n    return getattr(backend, \"api_version\", None) == SERVE_BACKEND_API_VERSION","tryCatchPattern":"try:\n    backend = registry.get(name)\nexcept RuntimeError as e:\n    if \"API version\" in str(e):\n        print(\"upgrade the plugin package to match this sglang release\")\n        raise","preventionTips":["Upgrade sglang and its backend plugins together as a set.","In CI, install plugins from the same release tag as sglang."],"tags":["sglang","cli","version-mismatch","plugin-abi"],"backgroundTag":"plugin-version-mismatch","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}