PrefectHQ/fastmcp · error · KeyError

Template {uri_template!r} version {version!r} not found

Error message

Template {uri_template!r} version {version!r} not found

What it means

remove_template with an explicit version builds f"{ResourceTemplate.make_key(uri_template)}@{version}" and raises KeyError if that key is absent. The pattern exists but not under the given version.

Source

Thrown at fastmcp_slim/fastmcp/server/providers/local_provider/local_provider.py:310

        Raises:
            KeyError: If no matching template is found.
        """
        if version is None:
            # Remove all versions
            keys_to_remove = [
                k
                for k, c in self._components.items()
                if isinstance(c, ResourceTemplate) and c.uri_template == uri_template
            ]
            if not keys_to_remove:
                raise KeyError(f"Template {uri_template!r} not found")
            for key in keys_to_remove:
                self._remove_component(key)
        else:
            # Remove specific version
            key = f"{ResourceTemplate.make_key(uri_template)}@{version}"
            if key not in self._components:
                raise KeyError(
                    f"Template {uri_template!r} version {version!r} not found"
                )
            self._remove_component(key)

    def remove_prompt(self, name: str, version: str | None = None) -> None:
        """Remove prompt(s) from this provider's storage.

        Args:
            name: The prompt name.
            version: If None, removes ALL versions. If specified, removes only that version.

        Raises:
            KeyError: If no matching prompt is found.
        """
        if version is None:
            # Remove all versions
            keys_to_remove = [
                k

View on GitHub (pinned to 1f02114297)

Solutions

  1. Omit version to remove all versions of the template
  2. Match the exact registered version string
  3. Catch KeyError for idempotent teardown

Example fix

// before
provider.remove_template("weather://{city}", "1.1")  # registered "1.0"
// after
provider.remove_template("weather://{city}")  # removes all versions
Defensive patterns

Strategy: validation

Validate before calling

key = f"{ResourceTemplate.make_key('weather://{city}')}@1.0"
if key not in provider._components:
    provider.remove_template("weather://{city}")

Type guard

def template_version_registered(provider, uri_template: str, version: str) -> bool:
    return f"{ResourceTemplate.make_key(uri_template)}@{version}" in provider._components

Try / catch

try:
    provider.remove_template("weather://{city}", "1.0")
except KeyError:
    logger.info("template version not present")

Prevention

When it happens

Trigger: provider.remove_template("weather://{city}", "1.1") when the template is unversioned or versioned as "1.0".

Common situations: Version string mismatch between registration and removal; removing after a prior partial cleanup already deleted that version; template registered without a version.

Related errors

AI-assisted analysis of PrefectHQ/fastmcp@1f02114297 (2026-08-29). Data as JSON: /api/errors/ebd161afe33287c4. Report an issue: GitHub.