What causes "Toolset '{toolset_name}' not found" in BerriAI/litellm?

List existing toolsets (dashboard or toolset DB table / API) and use the exact name.

BerriAI/litellm · error · HTTPException

Toolset '{toolset_name}' not found

Error message

Toolset '{toolset_name}' not found

What it means

On tools/list, a non-empty toolset_name query parameter is looked up in the database (cached); an unknown name raises 404 with this message. It requires the Prisma DB to be connected - a missing DB surfaces a different error from get_prisma_client_or_throw. Toolsets narrow the visible MCP servers/tools to a named grouping.

Source

Thrown at litellm/proxy/_experimental/mcp_server/rest_endpoints.py:690

        toolset_name: str | None,
        user_api_key_dict: UserAPIKeyAuth,
    ) -> UserAPIKeyAuth:
        """The one credential this tools request acts as.

        A toolset name narrows the caller's own credential to that toolset; otherwise a dashboard
        session is swapped for its admitted subject. The two are mutually exclusive by construction,
        which is why they share an owner: the admitted subject resolves per grant source and a team
        source deliberately carries none of the caller's ``object_permission``, so a toolset
        narrowing layered on top would evaporate on every team-granted server."""
        if not toolset_name:
            return await acting_user_auth(user_api_key_dict)

        from litellm.proxy.utils import get_prisma_client_or_throw

        prisma_client: Final = get_prisma_client_or_throw("Database not available. Connect a database to your proxy")
        toolset: Final = await global_mcp_server_manager.get_toolset_by_name_cached(prisma_client, toolset_name)
        if toolset is None:
            raise HTTPException(
                status_code=404,
                detail=f"Toolset '{toolset_name}' not found",
            )
        return await _apply_toolset_scope(user_api_key_dict, toolset.toolset_id)

    @router.get("/tools/list", dependencies=[Depends(user_api_key_auth)])
    async def list_tool_rest_api(
        request: Request,
        server_id: str | None = Query(None, description="The server id to list tools for"),
        mcp_server_name: str | None = Query(None, description="Filter tools to a single MCP server by name or alias"),
        toolset_name: str | None = Query(None, description="Filter tools to a single toolset by name"),
        include_disabled_tools: bool = Query(
            False,
            description=(
                "Admin only. Return the full server tool catalog without the "
                "allowed_tools filter or per-key tool permissions, so the MCP "
                "settings UI can configure the allowlist. Ignored for non-admins."
            ),

View on GitHub (pinned to 77b7c6c40c)

Solutions

List existing toolsets (dashboard or toolset DB table / API) and use the exact name.
If the toolset was renamed or deleted, update the caller to the current name or recreate the toolset.
Confirm the proxy is connected to the DB where the toolset lives.

Defensive patterns

Strategy: validation

Validate before calling

async def toolset_exists(client, name: str) -> bool:
    resp = await client.get(f"{proxy}/mcp/toolsets", headers=headers)  # or DB/toolset API
    return any(t.get("name") == name for t in resp.json().get("toolsets", []))

assert await toolset_exists(client, wanted), f"unknown toolset {wanted}"

Try / catch

resp = await client.get(f"{proxy}/mcp/tools/list", params={"toolset_name": name}, headers=headers)
if resp.status_code == 404 and f"Toolset '{name}' not found" in resp.text:
    raise UnknownToolset(name) from None  # permanent: fix the name, do not retry
resp.raise_for_status()

Prevention

Resolve toolset names once at startup and fail fast on unknown ones.
Parameterize toolset names per environment instead of hardcoding dev names into prod calls.
Re-check saved queries/dashboards after renaming or deleting toolsets.

When it happens

Trigger: GET /mcp/tools/list?toolset_name=... with a typo'd, deleted, or not-yet-created toolset name; using a toolset id instead of its name; querying an environment whose DB lacks the row.

Common situations: Toolsets created in one environment (dev) but referenced in another (prod); renamed toolsets breaking saved dashboards/queries; copy-paste of ids from the UI where names are expected.

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

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