BerriAI/litellm · error · ValueError

Tool search tool must have a valid name

Error message

Tool search tool must have a valid name

What it means

For the regex-based tool-search tool (type 'tool_search_tool_regex_20251119'), LiteLLM reads tool.get('name', 'tool_search_tool_regex') and requires the result to be a string. A non-string name (int, dict, None explicitly set) triggers this ValueError during request transformation.

Source

Thrown at litellm/llms/anthropic/chat/transformation.py:735

                if k != "type" and k != "name":
                    additional_tool_params[k] = v

            returned_tool = AnthropicHostedTools(
                type=tool["type"],
                name=function_name,
                **additional_tool_params,
            )
        elif tool["type"] == "url":  # mcp server tool
            mcp_server = AnthropicMcpServerTool(**tool)
        elif tool["type"] == "mcp":
            mcp_server = self._map_openai_mcp_server_tool(cast(OpenAIMcpServerTool, tool))
        elif tool["type"] == "tool_search_tool_regex_20251119":
            # Tool search tool using regex
            from litellm.types.llms.anthropic import AnthropicToolSearchToolRegex

            tool_name_obj = tool.get("name", "tool_search_tool_regex")
            if not isinstance(tool_name_obj, str):
                raise ValueError("Tool search tool must have a valid name")
            tool_name = tool_name_obj
            returned_tool = AnthropicToolSearchToolRegex(
                type="tool_search_tool_regex_20251119",
                name=tool_name,
            )
        elif tool["type"] == "tool_search_tool_bm25_20251119":
            # Tool search tool using BM25
            from litellm.types.llms.anthropic import AnthropicToolSearchToolBM25

            tool_name_obj = tool.get("name", "tool_search_tool_bm25")
            if not isinstance(tool_name_obj, str):
                raise ValueError("Tool search tool must have a valid name")
            tool_name = tool_name_obj
            returned_tool = AnthropicToolSearchToolBM25(
                type="tool_search_tool_bm25_20251119",
                name=tool_name,
            )
        elif tool["type"] == ANTHROPIC_ADVISOR_TOOL_TYPE:

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Set 'name' to a plain string (or remove the key to use the default 'tool_search_tool_regex').
2. Check the exact spelling: only the type key must equal 'tool_search_tool_regex_20251119'.
3. Validate types in config loading if tools come from YAML/JSON files where nesting is easy to get wrong.

Example fix

# before
{"type": "tool_search_tool_regex_20251119", "name": {"first": "x"}}

# after
{"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"}
# or simply omit 'name' entirely

if "name" in tool and not isinstance(tool["name"], str):
    del tool["name"]  # let LiteLLM apply the default
# or: tool["name"] = str(tool["name"]) if errors acceptable

def is_valid_tool_search_tool(tool) -> bool:
    if tool.get("type") not in ("tool_search_tool_regex_20251119", "tool_search_tool_bm25_20251119"):
        return True  # not this tool kind
    name = tool.get("name")
    return name is None or isinstance(name, str)

When it happens

Trigger: Passing {'type': 'tool_search_tool_regex_20251119', 'name': 123} or 'name': {'value': 'x'} — a name key present but not a string. Omitting name entirely is fine (default applied); only a wrong-typed value fails.

Common situations: Tool dicts produced by serialization layers that coerce values (e.g. YAML config turning a quoted key into a mapping); LLM-generated tool JSON with nested name objects; programmatic construction bugs.

Related errors

• Missing required parameter: parameters
• Missing required parameter: display_width_px or display_heig
• Missing required parameter: name
• Advisor tool must have a valid model
• Unsupported tool type: {tool['type']}

AI-assisted analysis of BerriAI/litellm@6c2dcb801b (2026-08-15). Data as JSON: /api/errors/e1ef3d76d03c9f13. Report an issue: GitHub.