PrefectHQ/fastmcp · error · NotFoundError

Unknown resource: {uri!r}

Error message

Unknown resource: {uri!r}

What it means

FastMCP raises NotFoundError("Unknown resource: {uri!r}") from read_resource when neither a concrete resource nor a matching resource template resolves for the requested URI (get_resource and get_resource_template both return None). This is the standard MCP 'not found' signal for resources/read.

Source

Thrown at fastmcp_slim/fastmcp/server/server.py:1664

                            ) from e
                        if is_timeout_error(e):
                            raise ResourceError(
                                "Upstream request timed out, please retry"
                            ) from e
                        # Standard masking logic
                        if self._mask_error_details:
                            raise ResourceError(
                                f"Error reading resource {uri!r}"
                            ) from e
                        raise ResourceError(
                            f"Error reading resource {uri!r}: {e}"
                        ) from e

                # Try templates (transforms + auth via get_resource_template)
                template = await self.get_resource_template(uri, version=version)
                if template is None:
                    if version is None:
                        raise NotFoundError(f"Unknown resource: {uri!r}")
                    raise NotFoundError(
                        f"Unknown resource: {uri!r} version {version!r}"
                    )
                span.set_attributes(template.get_span_attributes())
                params = template.matches(uri)
                assert params is not None

                # Path-security screening: reject traversal / absolute-path /
                # null-byte payloads in extracted parameter values BEFORE the
                # handler runs. This is the single chokepoint for every
                # templated read (local decorator and provider-sourced), so
                # enforcement lives here rather than in any decorator.
                security = template.resolve_security(self._resource_security)
                if security is not None:
                    failed = security.validate(params)
                    if failed is not None:
                        logger.debug(
                            "Rejected resource %r: parameter %r failed "

View on GitHub (pinned to 1f02114297)

Solutions

1. List available resources (`await server.get_resources()` / client.list_resources) and confirm the exact URI.
2. Correct the URI in the caller to match a registered resource or template pattern.
3. Register the missing resource or fix the template pattern so it matches the requested URI.
4. Check that the resource wasn't disabled, removed by transforms, or filtered by middleware/provider routing.

Example fix

// before
content = await client.read_resource("data://users/42")   # template is "user://{id}"
// after
content = await client.read_resource("data://user/42")    # matches registered template

available = {str(r.uri) for r in await client.list_resources()}
if uri not in available:
    raise ValueError(f"{uri} is not a registered resource")
await client.read_resource(uri)

try:
    result = await client.read_resource(uri)
except NotFoundError:
    print(f"{uri} unknown — call client.list_resources() for valid URIs")

When it happens

Trigger: Calling `read_resource(uri)` with a URI that was never added (typo, wrong scheme), a template whose parameters don't match the URI, a resource removed/disabled, or via client.read_resource on a server that doesn't expose it.

Common situations: Typos in URI scheme or path; client pointing at the wrong server; resource registered under a different name/URI; template pattern mismatch (e.g. 'user://{id}' vs requested 'users/42'); forgetting @resource decorator execution.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Unknown resource: {uri!r} version {version!r}
• Resource {uri!r} not found
• Unsupported content type: {type(item)}
• Remote server returned empty content for {parameterized_uri}
• Error reading resource {uri!r}

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