PrefectHQ/fastmcp · error · ValueError

ClientGroup requires at least one client

Error message

ClientGroup requires at least one client

What it means

ClientGroup fans out MCP operations across multiple named clients; constructing it with an empty mapping leaves nothing to operate on, so `__init__` raises this ValueError immediately. It is eager, fail-fast argument validation.

Source

Thrown at fastmcp_slim/fastmcp/client/group.py:44

    server_name: str
    client: Client[Any]
    upstream_name: str


class ClientGroup:
    """Coordinate independent clients without introducing a proxy server.

    Each client retains its own transport, session, capabilities, and protocol
    version. The group only combines tool discovery and routes tool calls.

    Callers may manage the clients' connections themselves or use the group as
    a convenience context manager. Entering an already-connected FastMCP client
    is safe because client contexts are reference counted.
    """

    def __init__(self, clients: Mapping[str, Client[Any]]) -> None:
        if not clients:
            raise ValueError("ClientGroup requires at least one client")

        self._clients = dict(clients)
        self._exit_stack: contextlib.AsyncExitStack | None = None
        self._tool_routes: dict[str, ToolRoute] = {}
        self._catalog_loaded = False
        self._route_lock = anyio.Lock()

    @property
    def clients(self) -> Mapping[str, Client[Any]]:
        """The group's clients, keyed by server name.

        Read-only: membership is fixed at construction, since discovered routes
        hold the client that advertised each tool and would silently go stale
        if the mapping were swapped underneath them.
        """
        return MappingProxyType(self._clients)

    @classmethod

View on GitHub (pinned to 1f02114297)

Solutions

1. Pass at least one client: ClientGroup({"server1": client1})
2. Check the config file actually defines servers before constructing the group
3. Build the mapping, check its length, or skip the group entirely when empty

Example fix

// before
clients = load_config_servers(path)  # may be {}
group = ClientGroup(clients)  # ValueError

// after
clients = load_config_servers(path)
if not clients:
    raise RuntimeError(f"No MCP servers configured in {path}")
group = ClientGroup(clients)

if not clients:
    raise ValueError("Cannot build ClientGroup: no servers configured")
group = ClientGroup(clients)

try:
    group = ClientGroup(clients)
except ValueError:
    logger.warning("no MCP servers configured; skipping group setup")
    group = None

When it happens

Trigger: `ClientGroup({})` or `ClientGroup(dict())` — e.g. a config file with no mcpServers entries, or a filtered dict that ended up empty.

Common situations: Empty or missing `mcpServers` section in the MCP config; environment-specific config with no servers; programmatically built client maps where all entries were filtered out.

Related errors

• Protocol mode for server {name!r} must be a string
• mode must be 'legacy', 'auto', or one of {list(MODERN_PROTOC
• a custom cache store requires CacheConfig.target_id for Fast
• Elicitation responses must be serializable as a JSON object
• Tool name collision: {public_name!r}

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