PrefectHQ/fastmcp · error · TypeError

Elicitation schema field '{prop_name}' is an object, but nes

Error message

Elicitation schema field '{prop_name}' is an object, but nested objects are not allowed. Elicitation schemas must be flat objects with primitive properties only.

What it means

MCP elicitation schemas must be flat: a property whose type is 'object' (a nested object) is not allowed. After passing the array checks, the validator rejects any remaining object-typed property to keep schemas limited to primitive fields.

Source

Thrown at fastmcp_slim/fastmcp/server/elicitation.py:506

                continue  # Allowed: {"type": "array", "items": {"enum": [...]}}

            # Allow arrays with oneOf/anyOf const patterns (SEP-1330)
            if "oneOf" in items_schema or "anyOf" in items_schema:
                union_schemas = items_schema.get("oneOf", []) + items_schema.get(
                    "anyOf", []
                )
                if union_schemas and all("const" in s for s in union_schemas):
                    continue  # Allowed: {"type": "array", "items": {"anyOf": [{"const": ...}, ...]}}

            # Reject other array types (e.g., arrays of primitives without enum pattern)
            raise TypeError(
                f"Elicitation schema field '{prop_name}' is an array, but arrays are only allowed "
                "when items are enums (for multi-select). Only enum arrays are supported in elicitation schemas."
            )

        # Check for nested objects (not allowed)
        if prop_type == "object":
            raise TypeError(
                f"Elicitation schema field '{prop_name}' is an object, but nested objects are not allowed. "
                "Elicitation schemas must be flat objects with primitive properties only."
            )

        # Check if it's a primitive type
        if prop_type not in ALLOWED_TYPES:
            raise TypeError(
                f"Elicitation schema field '{prop_name}' has type '{prop_type}' which is not "
                f"a primitive type. Only {ALLOWED_TYPES} are allowed in elicitation schemas."
            )

View on GitHub (pinned to 1f02114297)

Solutions

Flatten nested models into primitive properties on the response type (e.g. address_city, address_zip)
Run separate elicitations per nested object
Move structured/nested data collection to a tool with structured output

Example fix

// before
class Address(BaseModel):
    city: str
class Form(BaseModel):
    address: Address
// after
class Form(BaseModel):
    address_city: str

Defensive patterns

Strategy: validation

Validate before calling

def check_no_nested_objects(schema: dict) -> None:
    for name, prop in schema.get("properties", {}).items():
        if prop.get("type") == "object":
            raise TypeError(f"field '{name}' is a nested object; flatten it")

Type guard

def has_nested_object_field(schema: dict) -> bool:
    return any(
        isinstance(p, dict) and p.get("type") == "object"
        for p in schema.get("properties", {}).values()
    )

Try / catch

try:
    schema = get_elicitation_schema(response_type)
except TypeError as e:
    if "nested objects are not allowed" in str(e):
        logger.error("flatten nested models into primitive fields")
        return None
    raise

Prevention

Keep elicitation response models flat: only str/int/float/bool/Enum/Literal fields
Flatten sub-models into prefixed primitive fields (address_city, address_zip)
Avoid dict-typed fields in elicitation models
Run schema validation in CI to catch nested models before deployment

When it happens

Trigger: A response model with a nested BaseModel/dataclass/dict field (e.g. address: Address) whose property schema is {"type": "object", ...} during get_elicitation_schema validation.

Common situations: Composing response models from sub-models; copying a config schema into an elicitation response type; Pydantic models with dict-typed fields.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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