TypeError
pydantic_ai.tool.PydanticAIToolFunctionSignatureError
Stack trace
Traceback (most recent call last):
File "app.py", line 42, in <module>
result = tool.run(input_data)
File "pydantic_ai/tool.py", line 128, in run
raise PydanticAIToolFunctionSignatureError(f"Function signature mismatch: {err}")
pydantic_ai.tool.PydanticAIToolFunctionSignatureError: Function signature mismatch: missing required positional argument 'name' Why it happens
Pydantic AI tools introspect the function signature to validate inputs against the Pydantic model schema. If the function parameters do not exactly match the model fields (missing, extra, or misnamed parameters), the tool raises this error to prevent runtime failures.
Detection
Catch PydanticAIToolFunctionSignatureError during tool initialization or execution and log the function signature and expected model fields to identify mismatches early.
Causes & fixes
Function parameters do not match the Pydantic model fields exactly (missing or extra parameters).
Ensure the function signature parameters exactly match the Pydantic model field names and types, including required and optional fields.
Parameter names in the function are misspelled or use different casing than the Pydantic model fields.
Rename function parameters to match the Pydantic model field names exactly, respecting case sensitivity.
Using default values in the function signature that conflict with Pydantic model defaults or required fields.
Align default values in the function signature with those defined in the Pydantic model or remove conflicting defaults.
Code: broken vs fixed
from pydantic_ai import PydanticAITool
class UserModel(BaseModel):
name: str
age: int
def process_user(age: int): # Missing 'name' parameter
return f"User age is {age}"
tool = PydanticAITool(model=UserModel, func=process_user)
result = tool.run({'name': 'Alice', 'age': 30}) # Raises PydanticAIToolFunctionSignatureErrorfrom pydantic import BaseModel
from pydantic_ai import PydanticAITool
class UserModel(BaseModel):
name: str
age: int
def process_user(name: str, age: int): # Fixed: parameters match model fields
return f"User {name} is {age} years old"
tool = PydanticAITool(model=UserModel, func=process_user)
result = tool.run({'name': 'Alice', 'age': 30})
print(result) # Works correctlyWorkaround
Wrap the tool.run call in try/except PydanticAIToolFunctionSignatureError, then manually validate and map input dict keys to function parameters before retrying.
Prevention
Always define Pydantic models and corresponding tool functions with matching parameter names and types, and use static type checking or linters to catch mismatches before runtime.