Cannot specify 'required=True' with 'default' or 'default_fa

Error message

Cannot specify 'required=True' with 'default' or 'default_factory'. Required parameters cannot have defaults.

What it means

ArgTransform rejects required=True combined with a default or default_factory, since a required parameter by definition must be supplied and cannot have a default. __post_init__ raises ValueError for this contradictory configuration.

Source

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

        """Validate that only one of default or default_factory is provided."""
        has_default = self.default is not NotSet
        has_factory = self.default_factory is not NotSet

        if has_default and has_factory:
            raise ValueError(
                "Cannot specify both 'default' and 'default_factory' in ArgTransform. "
                "Use either 'default' for a static value or 'default_factory' for a callable."
            )

        if has_factory and not self.hide:
            raise ValueError(
                "default_factory can only be used with hide=True. "
                "Visible parameters must use static 'default' values since JSON schema "
                "cannot represent dynamic factories."
            )

        if self.required is True and (has_default or has_factory):
            raise ValueError(
                "Cannot specify 'required=True' with 'default' or 'default_factory'. "
                "Required parameters cannot have defaults."
            )

        if self.hide and self.required is True:
            raise ValueError(
                "Cannot specify both 'hide=True' and 'required=True'. "
                "Hidden parameters cannot be required since clients cannot provide them."
            )

        if self.required is False:
            raise ValueError(
                "Cannot specify 'required=False'. Set a default value instead."
            )


class ArgTransformConfig(FastMCPBaseModel):
    """A model for requesting a single argument transform."""

View on GitHub (pinned to 1f02114297)

Solutions

Drop required=True if the parameter should fall back to the default.
Drop default/default_factory if the parameter must be required.
If defaults come from shared config, strip them when setting required=True.

Example fix

// before
ArgTransform(required=True, default="x")

// after
ArgTransform(required=True)

Defensive patterns

Strategy: validation

Validate before calling

def check_required_default(t: ArgTransform) -> None:
    if t.required is True and (t.default is not NotSet or t.default_factory is not NotSet):
        raise ValueError("required=True cannot coexist with a default")

Try / catch

try:
    t = ArgTransform(required=True, default="x")
except ValueError:
    t = ArgTransform(default="x")  # default implies optional

Prevention

Treat required=True as exclusive: no defaults allowed.
If a fallback exists, the param is optional by definition — drop required=True.
Never copy a required flag from schema-style configs into ArgTransform blindly.

When it happens

Trigger: ArgTransform(required=True, default=...) or ArgTransform(required=True, default_factory=...).

Common situations: Trying to mark a parameter mandatory while also giving it a fallback value; merging parameter metadata where requiredness and defaults come from different sources.

Related errors

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