OpenBB-finance/OpenBB · error · ValueError

Category '{category}' not found. Available categories: {', '

Error message

Category '{category}' not found. Available categories: {', '.join(sorted(available))}

What it means

Raised by the OpenBB MCP server's list-tools-by-category tool when the requested category string does not exist in the server's category index. The index is built from the OpenBB router tree, so a category only exists if the corresponding extension is installed and loaded. The error message lists all valid categories to guide correction.

Source

Thrown at openbb_platform/extensions/mcp_server/openbb_mcp_server/app/app.py:635

        @mcp.tool(tags={"admin"})
        async def available_tools(
            category: Annotated[
                str, Field(description="The category of tools to list")
            ],
            subcategory: Annotated[
                str | None,
                Field(
                    description="Optional subcategory to filter by. "
                    "Use 'general' for tools directly under the category."
                ),
            ] = None,
        ) -> list[ToolInfo]:
            """List tools in a specific category and subcategory."""
            cat_data = category_index.get_subcategories(category)

            if cat_data is None:
                available = list(category_index.get_categories().keys())
                raise ValueError(
                    f"Category '{category}' not found. "
                    f"Available categories: {', '.join(sorted(available))}"
                )

            if subcategory:
                names = category_index.get_subcategory_names(category, subcategory)
                if not names:
                    raise ValueError(
                        f"Subcategory '{subcategory}' not found in category '{category}'. "
                        f"Available subcategories: {', '.join(sorted(cat_data.keys()))}"
                    )
            else:
                names = category_index.get_category_names(category)

            # Resolve active state from FastMCP's live tool list
            active_tools = await mcp.list_tools()
            active_names = {t.name for t in active_tools}

View on GitHub (pinned to 3e071fcc2c)

Solutions

Read the error message: it enumerates the available categories; use one of those exact strings.
Install/enable the extension that provides the missing category (e.g. pip install openbb-fixedincome) and restart the MCP server.
Call the category-listing tool first and derive names dynamically instead of hardcoding.
Check exact casing and spelling — category keys are matched literally, not case-insensitively.

Example fix

# before
tools = await list_category_tools(category="FixedIncome")

# after
cats = await list_categories()  # discover valid keys first
tools = await list_category_tools(category=cats["fixedincome"] if "fixedincome" in cats else sorted(cats)[0])

Defensive patterns

Strategy: validation

Validate before calling

async def safe_list_category_tools(mcp_client, category: str):
    cats = (await mcp_client.call_tool("list_categories", {})).result
    if category not in {c["name"] for c in cats}:
        raise KeyError(f"unknown category {category!r}; known: {sorted(c['name'] for c in cats)}")
    return await mcp_client.call_tool("list_category_tools", {"category": category})

Type guard

def is_known_category(category: str, known: set[str]) -> bool:
    return isinstance(category, str) and category in known

Try / catch

try:
    tools = await list_category_tools(category=cat)
except ValueError as e:
    if "not found. Available categories:" in str(e):
        available = str(e).split("Available categories:")[-1]
        cat = choose(available)  # re-ask user / pick programmatically
        tools = await list_category_tools(category=cat)
    else:
        raise

Prevention

Always enumerate categories dynamically instead of hardcoding names.
Validate user-supplied category strings against the listing tool output.
Keep MCP client prompts in sync with the installed OpenBB extensions.

When it happens

Trigger: Calling list_category_tools(category="fixedincome") when the fixedincome extension is not installed/enabled; passing a category name with different casing, whitespace, or a plural/singular mismatch (e.g. 'stocks' vs 'stock'); referencing a category from an older OpenBB version after a rename.

Common situations: MCP client (Claude, etc.) hardcoding a category name that no longer exists; partial openbb installation where only some extensions are installed; version upgrades that renamed router categories.

Related errors

AI-assisted analysis of OpenBB-finance/OpenBB@3e071fcc2c (2026-08-14). Data as JSON: /api/errors/ec5aab44416994e7. Report an issue: GitHub.