PrefectHQ/fastmcp · error · TypeError

Elicitation schema field '{prop_name}' has type '{prop_type}

Error message

Elicitation schema field '{prop_name}' has type '{prop_type}' which is not a primitive type. Only {ALLOWED_TYPES} are allowed in elicitation schemas.

What it means

FastMCP elicitation schemas must be flat objects whose properties are primitive JSON types. validate_elicitation_json_schema inspects each property's declared 'type' and raises TypeError if it is not one of ALLOWED_TYPES (string, number, integer, boolean, plus enum variants). Nested objects and arbitrary arrays are rejected because elicitation responses must map to simple form fields.

Source

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

                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 the schema: replace nested objects with individual primitive properties (e.g. use 'address_line1', 'city' instead of an 'address' object).
Use an enum array for multi-select instead of arbitrary arrays: {'type':'array','items':{'type':'string','enum':[...]}} which is allowed.
Remove or rename properties with misspelled types so each property.type is one of the allowed primitives.
If complex input is required, split elicitation into multiple sequential primitive-only requests or collect data via a tool instead.

Example fix

// before
schema = {"type": "object", "properties": {"address": {"type": "object", "properties": {"city": {"type": "string"}}}}}
// after
schema = {"type": "object", "properties": {"city": {"type": "string"}}}

Defensive patterns

Strategy: validation

Validate before calling

ALLOWED = {"string", "number", "integer", "boolean"}
def validate_flat(schema):
    for name, prop in schema.get("properties", {}).items():
        t = prop.get("type")
        items = prop.get("items", {})
        if t == "array" and items.get("type") != "string" or items.get("enum") is None and t == "array":
            raise TypeError(f"{name}: arrays must be enum arrays")
        if t not in ALLOWED and t != "array":
            raise TypeError(f"{name}: type '{t}' is not a primitive")

Type guard

def is_primitive_schema(prop: dict) -> bool:
    return prop.get("type") in {"string", "number", "integer", "boolean"}

Try / catch

try:
    schema = tool._get_elicitation_schema()
except TypeError as e:
    logger.error("Flatten elicitation schema: %s", e)
    schema = flatten_schema(schema)

Prevention

Design elicitation schemas as flat forms with primitive fields only
Use enum arrays for multi-select instead of arrays of objects
Derive schemas from flat pydantic models, not nested ones
Unit-test get_elicitation_schema() for every tool that elicits input

When it happens

Trigger: Calling get_elicitation_schema (or passing an elicitation schema through a tool) where a property in properties has a 'type' like 'object', 'array' (non-enum), or is missing/unrecognized, causing prop_type not in ALLOWED_TYPES.

Common situations: Developers porting a full JSON Schema designed for structured output (nested dicts, arrays of objects) into an elicitation request; hand-written schemas with typos in the type name; schemas generated from pydantic models with nested model fields.

Related errors

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