OpenBB-finance/OpenBB · error · ValueError

Subcategory '{subcategory}' not found in category '{category

Error message

Subcategory '{subcategory}' not found in category '{category}'. Available subcategories: {', '.join(sorted(cat_data.keys()))}

What it means

Raised by the OpenBB MCP server when a valid category is given but the subcategory filter does not exist under it. get_subcategory_names() returns an empty list for unknown subcategories, and the view raises with the sorted list of valid subcategories for that category. It is a pure input-validation error on the category/subcategory pair.

Source

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

                    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}

            # Build descriptions — use live tool object when available,
            # fall back to cached short description from the index.
            tool_map = {t.name: t for t in active_tools}
            results: list[ToolInfo] = []
            for name in sorted(names):
                if name in tool_map:
                    desc = _extract_brief_description(tool_map[name].description or "")
                else:

View on GitHub (pinned to 3e071fcc2c)

Solutions

Use the subcategory names printed in the error's 'Available subcategories' list, exactly as shown.
Call the category listing without subcategory first to inspect the hierarchy.
Pass subcategory='general' only when you want tools directly under the category (as documented on the parameter).
Update the openbb extensions so subcategory names match what your client expects.

Example fix

# before
tools = await list_category_tools(category="economy", subcategory="GDP")

# after
tools = await list_category_tools(category="economy", subcategory="gdp")  # exact key from error listing

Defensive patterns

Strategy: validation

Validate before calling

async def valid_subcategory(mcp_client, category: str, subcategory: str) -> bool:
    result = await mcp_client.call_tool("list_category_tools", {"category": category})
    subcats = set(result.result.get("subcategories", {}))
    return subcategory in subcats or subcategory == "general"

Type guard

def is_valid_subcategory(sub: str, cat_data: dict) -> bool:
    return isinstance(sub, str) and (sub in cat_data or sub == "general")

Try / catch

try:
    tools = await list_category_tools(category=cat, subcategory=sub)
except ValueError as e:
    if "Available subcategories:" in str(e):
        sub = str(e).split("Available subcategories:")[-1].strip().split(",")[0].strip(" '[]")
        tools = await list_category_tools(category=cat, subcategory=sub)
    else:
        raise

Prevention

Discover the subcategory hierarchy with a listing call before filtering.
Treat category/subcategory keys as opaque API identifiers — copy them exactly.
Re-validate hardcoded names whenever OpenBB extensions are upgraded.

When it happens

Trigger: Calling list_category_tools(category='economy', subcategory='gdp') when 'gdp' is not a subcategory key under economy; using 'general' when the category has no direct tools; typos or renamed subcategories after an OpenBB upgrade.

Common situations: Clients guessing subcategory names from endpoint paths; extension version drift renaming router children; omitting subcategory vs using 'general' incorrectly.

Related errors

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