{"record":{"id":"05dba990cdae54bb","repo":"sgl-project/sglang","slug":"failed-to-load-serve-backend-name-r-from-self","errorCode":null,"errorMessage":"Failed to load serve backend {name!r} from {self._entry_point_provider(entry_point)}: {exc}","messagePattern":"Failed to load serve backend (.+?) from (.+?): (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"python/sglang/cli/serve_backends.py","lineNumber":149,"sourceCode":"        if len(candidates) > 1:\n            providers = \", \".join(\n                sorted(\n                    self._entry_point_provider(candidate) for candidate in candidates\n                )\n            )\n            raise RuntimeError(\n                f\"Multiple distributions register serve backend {name!r}: \"\n                f\"{providers}. Uninstall one provider or choose another backend name.\"\n            )\n\n        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,","sourceCodeStart":131,"sourceCodeEnd":167,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/cli/serve_backends.py#L131-L167","documentation":"Raised when the backend's entry-point factory fails to load or call — the entry point resolves but entry_point.load() or factory() raises, or the resolved object is not callable. The RuntimeError chains the original exception and names the provider distribution, distinguishing load failures from unknown or ambiguous names.","triggerScenarios":"A plugin whose factory module has an ImportError (missing dependency); a factory that raises during instantiation (bad config, missing env var); an entry point pointing at a non-callable attribute; calling registry.get(name) for such a backend.","commonSituations":"Plugin package missing a runtime dependency in the user's env; plugin built against an older sglang internal API that moved; entry point pointing to a class instead of a factory function.","solutions":["Read the chained `: {exc}` part — the underlying exception is the real cause; fix that first (install missing deps, fix the plugin import).","Upgrade or reinstall the provider package to match your sglang version.","Ensure the entry point targets a zero-arg callable factory (function or class), not an instance or module.","Uninstall the broken plugin and use the built-in 'llm' backend if it fits."],"exampleFix":"# pyproject.toml — before: points at a non-callable\n[project.entry-points.'sglang.serve_backends']\nmybackend = \"my_pkg.backend:BACKEND_INSTANCE\"\n# after\nmybackend = \"my_pkg.backend:make_backend\"","handlingStrategy":"try-catch","validationCode":"from importlib.metadata import entry_points\nep = next(iter(entry_points(group=\"sglang.serve_backends\", name=name)), None)\nif ep is None:\n    raise SystemExit(\"backend not installed\")\ntry:\n    assert callable(ep.load()), \"factory must be callable\"\nexcept Exception:\n    raise SystemExit(f\"backend {name} is broken; see chained error\")","typeGuard":null,"tryCatchPattern":"try:\n    backend = registry.get(name)\nexcept RuntimeError as e:\n    if \"Failed to load serve backend\" in str(e) and e.__cause__:\n        log.exception(\"plugin load failed\", exc_info=e.__cause__)","preventionTips":["Smoke-test plugin imports (`import plugin_pkg`) in a startup healthcheck.","Keep plugin dependency pins in sync with sglang releases.","Fail fast in the plugin factory with clear errors so the chained message is actionable."],"tags":["sglang","cli","entry-points","plugin-load-failure","import-error"],"backgroundTag":"plugin-initialization-failed","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}