Cannot specify 'required=False'. Set a default value instead

Error message

Cannot specify 'required=False'. Set a default value instead.

What it means

ArgTransform does not accept required=False. Optional-ness is expressed by providing a default (or default_factory), so explicitly setting required=False is considered a misconfiguration and __post_init__ raises ValueError directing you to set a default instead.

Source

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

                "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."""

    name: str | None = Field(default=None, description="The new name for the argument.")
    description: str | None = Field(
        default=None, description="The new description for the argument."
    )
    default: str | int | float | bool | None = Field(
        default=None, description="The new default value for the argument."
    )
    hide: bool = Field(
        default=False, description="Whether to hide the argument from the tool."
    )
    required: Literal[True] | None = Field(

View on GitHub (pinned to 1f02114297)

Solutions

Remove required=False and set default=<value> to make the parameter optional.
Use default_factory= (with hide=True) if the optional value is computed.
Omit the required field entirely (leave it as NotSet) when the transform shouldn't change requiredness.

Example fix

// before
ArgTransform(name="limit", required=False)

// after
ArgTransform(name="limit", default=10)

Defensive patterns

Strategy: validation

Validate before calling

def check_required_false(t: ArgTransform) -> None:
    if t.required is False:
        raise ValueError("Use default= instead of required=False")

Try / catch

try:
    t = ArgTransform(name="limit", required=False)
except ValueError:
    t = ArgTransform(name="limit", default=10)

Prevention

Never set the required field to False; express optionality via default.
Omit required entirely unless you mean True.
Strip required keys from generic config payloads before constructing ArgTransform.

When it happens

Trigger: ArgTransform(required=False), typically when copying a schema-like config or trying to 'make a param optional' without a default.

Common situations: Porting JSON-schema-style thinking (required: false) into ArgTransform; constructing transforms from generic config files that always include a required key.

Related errors

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