{"record":{"id":"bce14fd38b7a6fa2","repo":"PrefectHQ/fastmcp","slug":"extension-self-identifier-r-is-not-bound-to-a-fa","errorCode":null,"errorMessage":"Extension {self.identifier!r} is not bound to a FastMCP server; register it with FastMCP.add_extension() before use.","messagePattern":"Extension (.+?) is not bound to a FastMCP server; register it with FastMCP\\.add_extension\\(\\) before use\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"fastmcp_slim/fastmcp/server/extensions.py","lineNumber":154,"sourceCode":"        if identifier is not None:\n            validate_extension_identifier(identifier, owner=cls.__name__)\n\n    def _bind(self, server: FastMCP) -> None:\n        \"\"\"Bind this extension to its FastMCP instance (called by `add_extension`).\n\n        A weak reference avoids a reference cycle between the server and its\n        extensions. Per-instance identifiers are validated here.\n        \"\"\"\n        validate_extension_identifier(self.identifier, owner=type(self).__name__)\n        self._server_ref = weakref.ref(server)\n\n    @property\n    def server(self) -> FastMCP:\n        \"\"\"The FastMCP server this extension is registered on.\n\n        Handlers, interceptors, and lifespan code reach the component registry,\n        `Context`, and auth scope through here. Raises if the extension has not\n        been registered with `FastMCP.add_extension()`.\n        \"\"\"\n        ref = self._server_ref\n        server = ref() if ref is not None else None\n        if server is None:\n            raise RuntimeError(\n                f\"Extension {self.identifier!r} is not bound to a FastMCP server; \"\n                \"register it with FastMCP.add_extension() before use.\"\n            )\n        return server\n\n    def settings(self) -> dict[str, Any]:\n        \"\"\"Per-extension settings advertised at `capabilities.extensions[identifier]`.\n\n        An empty dict (the default) advertises the extension with no settings.\n        \"\"\"\n        return {}\n\n    def methods(self) -> Sequence[MethodBinding]:","sourceCodeStart":136,"sourceCodeEnd":172,"githubUrl":"https://github.com/PrefectHQ/fastmcp/blob/1f021142978e0861cd910c8df4e8074bc7cf3978/fastmcp_slim/fastmcp/server/extensions.py#L136-L172","documentation":"ServerExtension.server is a weakly-referenced property pointing at the FastMCP instance the extension was registered on. Accessing it before FastMCP.add_extension() has been called (or after the server was garbage-collected) finds no live server and raises RuntimeError.","triggerScenarios":"Calling extension.server inside handler/interceptor/lifespan code before registration; instantiating an extension and probing .server immediately; the server object being dropped so the weakref is dead.","commonSituations":"Unit tests constructing an extension in isolation; module-level extension objects used at import time before the server exists; holding extensions across server restarts.","solutions":["Register the extension first: server = FastMCP(...); server.add_extension(ext), then access ext.server.","Only access ext.server from within handlers/interceptors/lifespan, which run after registration.","Keep a direct reference to your FastMCP instance in application code instead of reaching through the extension.","If the server may have been garbage collected, re-create/re-register the extension on the live server."],"exampleFix":"// before\next = MyExtension()\nregistry = ext.server._component_manager  # RuntimeError: not bound\n// after\nserver = FastMCP(\"demo\")\nserver.add_extension(ext)\nregistry = ext.server._component_manager","handlingStrategy":"try-catch","validationCode":"def extension_bound(ext) -> bool:\n    ref = getattr(ext, \"_server_ref\", None)\n    return bool(ref and ref() is not None)","typeGuard":"def is_bound(ext) -> bool:\n    return ext._server_ref is not None and ext._server_ref() is not None","tryCatchPattern":"try:\n    server = ext.server\nexcept RuntimeError:\n    server = None  # defer until after add_extension()","preventionTips":["Always call FastMCP.add_extension(ext) before touching ext.server","Access ext.server only from handlers/interceptors/lifespan callbacks","Keep a strong reference to the FastMCP instance so the weakref stays alive"],"tags":["extensions","lifecycle","initialization-order"],"backgroundTag":"object-not-initialized","analyzedSha":"1f021142978e0861cd910c8df4e8074bc7cf3978","analyzedAt":"2026-08-29T14:31:16.082Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}