BerriAI/litellm · error · RuntimeError

Unable to assign a unique short MCP tool prefix for server {

Error message

Unable to assign a unique short MCP tool prefix for server {server.server_id} after {self._SHORT_PREFIX_MAX_REHASH_ATTEMPTS} attempts; the 3-character prefix space is too crowded.

What it means

Error "Unable to assign a unique short MCP tool prefix for server {server.server_id} after {self._SHORT_PREFIX_MAX_REHASH_ATTEMPTS} attempts; the 3-character prefix space is too crowded." thrown in BerriAI/litellm.

Source

Thrown at litellm/proxy/_experimental/mcp_server/mcp_server_manager.py:4337

            candidate = compute_short_server_prefix(server.server_id, attempt=attempt)
            if candidate not in used:
                server.short_prefix = candidate
                if attempt > 0:
                    verbose_logger.info(
                        "MCP short-prefix collision resolved for server %s: "
                        "natural hash collided with %s, using rehashed prefix "
                        "%s (attempt=%d).",
                        server.server_id,
                        used.get(
                            compute_short_server_prefix(server.server_id, attempt=0),
                            "<unknown>",
                        ),
                        candidate,
                        attempt,
                    )
                return

        raise RuntimeError(
            f"Unable to assign a unique short MCP tool prefix for server "
            f"{server.server_id} after {self._SHORT_PREFIX_MAX_REHASH_ATTEMPTS} "
            "attempts; the 3-character prefix space is too crowded."
        )

    def _create_prefixed_tools(self, tools: list[MCPTool], server: MCPServer, add_prefix: bool = True) -> list[MCPTool]:
        """
        Create prefixed tools and update tool mapping.

        Args:
            tools: List of original tools from server
            server: Server instance

        Returns:
            List of tools with prefixed names
        """
        prefixed_tools: Final = []
        prefix: Final = get_server_prefix(server)

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Reduce the number of registered MCP servers, or configure explicit tool prefixes to free the 3-character prefix space.

Example fix

Set a custom tool prefix for some servers.

When it happens

Trigger: Thrown at litellm/proxy/_experimental/mcp_server/mcp_server_manager.py:4337 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/7f405e42cdabc0e1. Report an issue: GitHub.