{"record":{"id":"5e504cab0aea08d1","repo":"PrefectHQ/fastmcp","slug":"cls-name-does-not-define-key-prefix-compone","errorCode":null,"errorMessage":"{cls.__name__} does not define KEY_PREFIX. Component keys will not be type-prefixed, which may cause collisions.","messagePattern":"(.+?) does not define KEY_PREFIX\\. Component keys will not be type-prefixed, which may cause collisions\\.","errorType":"console","errorClass":"UserWarning","httpStatus":null,"severity":"warning","filePath":"fastmcp_slim/fastmcp/utilities/components.py","lineNumber":81,"sourceCode":"    if \"@\" in version:\n        raise ValueError(\n            f\"Version string cannot contain '@' (used as key delimiter): {version!r}\"\n        )\n    return version\n\n\nclass FastMCPComponent(FastMCPBaseModel):\n    \"\"\"Base class for FastMCP tools, prompts, resources, and resource templates.\"\"\"\n\n    KEY_PREFIX: ClassVar[str] = \"\"\n\n    def __init_subclass__(cls, **kwargs: Any) -> None:\n        super().__init_subclass__(**kwargs)\n        # Warn if a subclass doesn't define KEY_PREFIX (inherited or its own)\n        if not cls.KEY_PREFIX:\n            import warnings\n\n            warnings.warn(\n                f\"{cls.__name__} does not define KEY_PREFIX. \"\n                f\"Component keys will not be type-prefixed, which may cause collisions.\",\n                UserWarning,\n                stacklevel=2,\n            )\n\n    name: str = Field(\n        description=\"The name of the component.\",\n    )\n    version: Annotated[str | None, BeforeValidator(_coerce_version)] = Field(\n        default=None,\n        description=\"Optional version identifier for this component. \"\n        \"Multiple versions of the same component (same name) can coexist.\",\n    )\n    title: str | None = Field(\n        default=None,\n        description=\"The title of the component for display purposes.\",\n    )","sourceCodeStart":63,"sourceCodeEnd":99,"githubUrl":"https://github.com/PrefectHQ/fastmcp/blob/1f021142978e0861cd910c8df4e8074bc7cf3978/fastmcp_slim/fastmcp/utilities/components.py#L63-L99","documentation":"`FastMCPComponent.__init_subclass__` requires every concrete component subclass to define a non-empty `KEY_PREFIX` so component keys are type-prefixed (e.g. `tool:`) and cannot collide across types. A subclass with an empty/missing `KEY_PREFIX` triggers this `UserWarning`.","triggerScenarios":"Defining a subclass of a component base (e.g. a custom `Resource`/`Tool` variant) without setting `KEY_PREFIX`, or overriding it to `\"\"`.","commonSituations":"Framework authors adding new component kinds; test doubles subclassing `FastMCPComponent` without keys; accidental override of an inherited prefix with an empty string.","solutions":["Set a unique class attribute: `KEY_PREFIX = \"mycomponent\"` on the subclass.","Choose a prefix that does not collide with built-ins (tool, resource, template, prompt).","For abstract intermediates that inherit a valid prefix, ensure you don't blank it out.","Key the registry lookups on the prefix so collisions surface immediately in tests."],"exampleFix":"// before\nclass SidebarComponent(FastMCPComponent):\n    pass\n// after\nclass SidebarComponent(FastMCPComponent):\n    KEY_PREFIX = \"sidebar\"","handlingStrategy":"validation","validationCode":"class Checklist:\n    @staticmethod\n    def validate_component_subclass(cls) -> None:\n        prefix = getattr(cls, \"KEY_PREFIX\", None)\n        assert prefix, f\"{cls.__name__} must define a non-empty KEY_PREFIX\"\n","typeGuard":"def has_key_prefix(cls) -> bool:\n    return bool(getattr(cls, \"KEY_PREFIX\", None))","tryCatchPattern":"import warnings\nwith warnings.catch_warnings(record=True) as caught:\n    warnings.simplefilter(\"always\")\n    class MyComponent(FastMCPComponent):\n        pass\nif any(\"KEY_PREFIX\" in str(w.message) for w in caught):\n    MyComponent.KEY_PREFIX = \"mycomponent\"  # or fail the build","preventionTips":["Define KEY_PREFIX on every concrete component subclass","Pick unique, collision-free prefixes","Add a test asserting KEY_PREFIX truthiness for all component classes"],"tags":["python","components","naming","subclassing"],"backgroundTag":"missing-key-prefix","analyzedSha":"1f021142978e0861cd910c8df4e8074bc7cf3978","analyzedAt":"2026-08-29T14:31:16.082Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}