PrefectHQ/fastmcp · error

Got unexpected keyword argument(s): {', '.join(sorted(unknow

Error message

Got unexpected keyword argument(s): {', '.join(sorted(unknown_args))}

What it means

The forwarded tool's _forward validates keyword arguments against the transformed tool's new schema. Any argument not present in the new (post-ArgTransform) schema is rejected with a TypeError, since the transformation renamed or removed the original parameter names.

Source

Thrown at fastmcp_slim/fastmcp/tools/tool_transform.py:736

            "properties": new_props,
            # Iterate props (not the set) for deterministic ordering
            "required": [p for p in new_props if p in new_required],
            "additionalProperties": False,
        }

        if parent_defs:
            schema["$defs"] = parent_defs
            schema = compress_schema(schema)

        # Create forwarding function that closes over everything it needs
        async def _forward(**kwargs: Any):
            # Validate arguments
            valid_args = set(new_props.keys())
            provided_args = set(kwargs.keys())
            unknown_args = provided_args - valid_args

            if unknown_args:
                raise TypeError(
                    f"Got unexpected keyword argument(s): {', '.join(sorted(unknown_args))}"
                )

            # Check required arguments
            missing_args = new_required - provided_args
            if missing_args:
                raise TypeError(
                    f"Missing required argument(s): {', '.join(sorted(missing_args))}"
                )

            # Map arguments to parent names
            parent_args = {}
            for new_name, value in kwargs.items():
                old_name = new_to_old.get(new_name, new_name)
                parent_args[old_name] = value

            # Add hidden defaults (constant values for hidden parameters)
            for old_name, transform in hidden_defaults.items():

View on GitHub (pinned to 1f02114297)

Solutions

1. Update the call site to use the new (transformed) parameter names
2. Inspect the transformed tool's schema to confirm valid argument names
3. Adjust the ArgTransform to keep the old name if backward compatibility is required

Example fix

// before
await transformed_tool(query="x")  # renamed to q

// after
await transformed_tool(q="x")

valid = set(transformed_tool.parameters["properties"].keys())
unknown = set(kwargs) - valid
if unknown:
    raise TypeError(f"Unknown args: {unknown}")

try:
    result = await transformed_tool(**kwargs)
except TypeError as e:
    if "unexpected keyword" in str(e):
        kwargs = {k: v for k, v in kwargs.items() if k in valid_args}
        result = await transformed_tool(**kwargs)
    else:
        raise

When it happens

Trigger: Calling the transformed tool with a keyword argument that was renamed or dropped by an ArgTransform, or using the parent tool's original parameter name after it was remapped to a new name.

Common situations: Caching old parameter names after refactoring the transform; LLM clients calling with stale tool schemas; renaming a parameter in an ArgTransform while callers still pass the old name.

Related errors

• Cannot specify both a name as first argument and as keyword
• First argument to @{decorator_name} must be a function, stri
• Cannot specify name both as first argument and keyword
• Invalid first argument: {type(name_or_fn)}
• A completion handler returned a str; return a list of string

AI-assisted analysis of PrefectHQ/fastmcp@1f02114297 (2026-08-29). Data as JSON: /api/errors/2c484717f8917b14. Report an issue: GitHub.