huggingface/smolagents · error · Exception

In tool '{self.name}', 'forward' method parameters were {act

Error message

In tool '{self.name}', 'forward' method parameters were {actual_keys}, but expected {expected_keys}. It should take 'self' as its first argument, then its next arguments should match the keys of tool attribute 'inputs'.

What it means

Tool.forward's parameter names (after self) must exactly match the keys of the tool's inputs dict, because smolagents forwards arguments to forward by keyword. A mismatch raises an exception listing actual vs expected keys.

Source

Thrown at src/smolagents/tools.py:207

                    f"Input '{input_name}': type must be a string or list of strings, got {type(input_content['type']).__name__}"
                )
            # Check all types are authorized
            invalid_types = [t for t in input_types if t not in AUTHORIZED_TYPES]
            if invalid_types:
                raise ValueError(f"Input '{input_name}': types {invalid_types} must be one of {AUTHORIZED_TYPES}")
        # Validate output type
        assert getattr(self, "output_type", None) in AUTHORIZED_TYPES

        # Validate forward function signature, except for Tools that use a "generic" signature (PipelineTool, SpaceToolWrapper, LangChainToolWrapper)
        if not (
            hasattr(self, "skip_forward_signature_validation")
            and getattr(self, "skip_forward_signature_validation") is True
        ):
            signature = inspect.signature(self.forward)
            actual_keys = set(key for key in signature.parameters.keys() if key != "self")
            expected_keys = set(self.inputs.keys())
            if actual_keys != expected_keys:
                raise Exception(
                    f"In tool '{self.name}', 'forward' method parameters were {actual_keys}, but expected {expected_keys}. "
                    f"It should take 'self' as its first argument, then its next arguments should match the keys of tool attribute 'inputs'."
                )

            json_schema = _convert_type_hints_to_json_schema(self.forward, error_on_missing_type_hints=False)[
                "properties"
            ]  # This function will not raise an error on missing docstrings, contrary to get_json_schema
            for key, value in self.inputs.items():
                assert key in json_schema, (
                    f"Input '{key}' should be present in function signature, found only {json_schema.keys()}"
                )
                if "nullable" in value:
                    assert "nullable" in json_schema[key], (
                        f"Nullable argument '{key}' in inputs should have key 'nullable' set to True in function signature."
                    )
                if key in json_schema and "nullable" in json_schema[key]:
                    assert "nullable" in value, (
                        f"Nullable argument '{key}' in function signature should have key 'nullable' set to True in inputs."

View on GitHub (pinned to 30bb116109)

Solutions

1. Make forward's parameters exactly the keys of self.inputs, in any order but with identical names
2. If the tool uses a generic signature (PipelineTool, SpaceToolWrapper, LangChainToolWrapper), set skip_forward_signature_validation = True
3. Add the missing key to self.inputs or the missing parameter to forward

Example fix

# before
class MyTool(Tool):
    inputs = {"query": {"type": "string", "description": "..."}}
    def forward(self, text): ...
# after
class MyTool(Tool):
    inputs = {"query": {"type": "string", "description": "..."}}
    def forward(self, query): ...

import inspect
def signature_matches(tool):
    params = {k for k in inspect.signature(tool.forward).parameters if k != "self"}
    return params == set(tool.inputs.keys())

assert signature_matches(MyTool())

import inspect
def tool_signature_valid(tool) -> bool:
    params = {k for k in inspect.signature(tool.forward).parameters if k not in ("self", "args", "kwargs")}
    return params == set(tool.inputs.keys())

When it happens

Trigger: Defining forward(self, text, temperature) while self.inputs keys are {"text", "temp"}, or renaming an inputs key without updating forward, or adding an extra parameter not declared in inputs (no **kwargs allowed).

Common situations: Refactoring tool code and renaming arguments in one place only; copy-pasting a Tool subclass and editing inputs but not forward; adding a new input entry but forgetting the function parameter.

Related errors

• You must set an attribute {attr}.
• Attribute {attr} should have type {expected_type.__name__},
• Attribute output_schema should have type dict, got {type(out
• Invalid Tool name '{self.name}': must be a valid Python iden
• Input '{input_name}': when type is a list, all elements must

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