huggingface/smolagents · error · ValueError

Tool {tool_name} is not recognized either as a default tool

Error message

Tool {tool_name} is not recognized either as a default tool or a Space.

What it means

Raised by run_smolagent in the smolagents CLI when a tool name passed via --tools is neither a key in TOOL_MAPPING (built-in default tools) nor resolvable as a Hugging Face Space. The CLI resolves each tool name in order: Space check, then default tool mapping, then raises this ValueError.

Source

Thrown at src/smolagents/cli.py:245

    provider: str | None = None,
    action_type: str = "code",
) -> None:
    load_dotenv()

    model = load_model(model_type, model_id, api_base=api_base, api_key=api_key, provider=provider)

    available_tools = []

    for tool_name in tools:
        if "/" in tool_name:
            space_name = tool_name.split("/")[-1].lower().replace("-", "_").replace(".", "_")
            description = f"Tool loaded from Hugging Face Space: {tool_name}"
            available_tools.append(Tool.from_space(space_id=tool_name, name=space_name, description=description))
        else:
            if tool_name in TOOL_MAPPING:
                available_tools.append(TOOL_MAPPING[tool_name]())
            else:
                raise ValueError(f"Tool {tool_name} is not recognized either as a default tool or a Space.")

    if action_type == "code":
        agent = CodeAgent(
            tools=available_tools,
            model=model,
            additional_authorized_imports=imports,
            stream_outputs=True,
        )
    elif action_type == "tool_calling":
        agent = ToolCallingAgent(tools=available_tools, model=model, stream_outputs=True)
    else:
        raise ValueError(f"Unsupported action type: {action_type}")

    agent.run(prompt)


def main() -> None:
    args = parse_arguments()

View on GitHub (pinned to 30bb116109)

Solutions

1. Check TOOL_MAPPING keys in smolagents/default_tools.py for the installed version and use the exact tool name.
2. If you meant a Space, verify the Space ID exists on huggingface.co and is reachable.
3. Upgrade smolagents if the tool was added in a newer release.

Example fix

# before
smolagent --tools web_serach --prompt "hi"
# after
smolagent --tools web_search --prompt "hi"

from smolagents.default_tools import TOOL_MAPPING
assert tool_name in TOOL_MAPPING, f'{tool_name} not a default tool; check TOOL_MAPPING keys'

When it happens

Trigger: Passing an unknown tool name to `smolagent --tools unknown_tool_name`, a typo of a default tool (e.g. 'web_serach'), or a Space ID that doesn't exist / isn't detected as a Space so it falls through to the mapping lookup and misses.

Common situations: Misspelling default tool names, referencing a tool that exists in the docs but not in the installed version's TOOL_MAPPING, or passing a nonexistent Space ID.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Unsupported model type: {model_type}
• Unsupported action type: {action_type}
• Each tool or managed_agent should have a unique name! You pa
• Only 'markdown' is supported for a string argument to `code_
• Unsupported engine: {self.engine}

AI-assisted analysis of huggingface/smolagents@30bb116109 (2026-08-28). Data as JSON: /api/errors/fdc98565847c751e. Report an issue: GitHub.