PrefectHQ/fastmcp · error · ResourceError

Remote server returned empty content for {backend_uri}

Error message

Remote server returned empty content for {backend_uri}

What it means

When the FastMCP proxy reads a resource from the remote backend, if _relay_read_resource returns an empty result list, a ResourceError('Remote server returned empty content for <uri>') is raised because a resource must yield at least one content item.

Source

Thrown at fastmcp_slim/fastmcp/server/providers/proxy.py:555

            return self._cached_content

        backend_uri = self._backend_uri or str(self.uri)
        with client_span(
            "resources/read",
            "resources/read",
            backend_uri,
            resource_uri=backend_uri,
        ) as span:
            span.set_attribute("fastmcp.provider.type", "ProxyProvider")
            client = await self._get_client()
            ctx = get_context()
            async with client:
                _stash_proxy_request_context(client, ctx)
                result = await _relay_read_resource(client, backend_uri, ctx)
            if isinstance(result, mcp_types.InputRequiredResult):
                return InputRequiredResourceResult(result)
            if not result:
                raise ResourceError(
                    f"Remote server returned empty content for {backend_uri}"
                )

            # Process all items in the result list, not just the first one
            contents: list[ResourceContent] = []
            for item in result:
                if isinstance(item, TextResourceContents):
                    contents.append(
                        ResourceContent(
                            content=item.text,
                            mime_type=item.mime_type,
                            meta=item.meta,
                        )
                    )
                elif isinstance(item, BlobResourceContents):
                    contents.append(
                        ResourceContent(
                            content=base64.b64decode(item.blob),

View on GitHub (pinned to 1f02114297)

Solutions

1. Verify the backend server returns content for that URI by querying it directly
2. Check the backend's resource implementation for early returns of empty lists/None
3. Upgrade backend and proxy to matching FastMCP versions
4. Catch ResourceError and return a placeholder/empty-content fallback

Example fix

// before
@server.resource('data://items')
def items():
    return None
// after
@server.resource('data://items')
def items():
    return [] if not data else data

async def backend_returns_content(backend_client, uri: str) -> bool:
    result = await backend_client.read_resource(uri)
    return bool(result)

try:
    content = await proxy_client.read_resource(uri)
except ResourceError as e:
    if 'empty content' in str(e):
        log.warning('backend returned nothing for %s', uri)
        content = fallback_content(uri)
    else:
        raise

When it happens

Trigger: client.read_resource('uri') on a proxy where the backend server responds successfully but with no resource contents (empty list of contents).

Common situations: Backend resource handler returns an empty/None result, backend and proxy version mismatch in resource result shape, backend bug for a particular URI.

Related errors

• Provided resource URI is invalid: {str(uri)!r}
• contents[{i}] must be ResourceContent, got {type(item).__nam
• contents must be str, bytes, or list[ResourceContent], got {
• Either name or uri must be provided
• Subclasses must implement read()

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