deepset-ai/haystack · error · ValueError

StateSchema: Key '{param}' is missing a 'type' entry.

Error message

StateSchema: Key '{param}' is missing a 'type' entry.

What it means

StateSchema validation raises this ValueError when a schema entry dict lacks the required 'type' key. Every parameter in a state schema must declare its Python type so the state container can validate and merge values.

Source

Thrown at haystack/components/agents/state/state.py:69

        if config.get("handler"):
            deserialized_schema[param]["handler"] = deserialize_callable(config["handler"])

    return deserialized_schema


def _validate_schema(schema: dict[str, Any]) -> None:
    """
    Validate that a schema dictionary meets all required constraints.

    Checks that each parameter definition has a valid type field and that any handler
    specified is a callable function.

    :param schema: Dictionary mapping parameter names to their type and handler configs
    :raises ValueError: If schema validation fails due to missing or invalid fields
    """
    for param, definition in schema.items():
        if "type" not in definition:
            raise ValueError(f"StateSchema: Key '{param}' is missing a 'type' entry.")
        if not _is_valid_type(definition["type"]):
            raise ValueError(f"StateSchema: 'type' for key '{param}' must be a Python type, got {definition['type']}")
        if definition.get("handler") is not None and not callable(definition["handler"]):
            raise ValueError(f"StateSchema: 'handler' for key '{param}' must be callable or None")
        if param == "messages":  # definition["type"] != list[ChatMessage] but split to cover also List[ChatMessage]
            if not _is_list_type(definition["type"]):
                raise ValueError(f"StateSchema: 'messages' must be of type list[ChatMessage], got {definition['type']}")
            # Check if the list contains ChatMessage elements
            args = get_args(definition["type"])
            if not args or not issubclass(args[0], ChatMessage):
                raise ValueError(f"StateSchema: 'messages' must be of type list[ChatMessage], got {definition['type']}")


class State:
    """
    State is a container for storing shared information during the execution of an Agent and its tools.

    For instance, State can be used to store documents, context, and intermediate results.

View on GitHub (pinned to e318778c9b)

Solutions

  1. Add a 'type' entry with a Python type to each schema key, e.g. {"param": {"type": list}}
  2. Check for typos: the key must be exactly 'type'
  3. If using serialized schemas, validate them with _validate_schema or a unit test before use

Example fix

// before
schema = {"numbers": {"handler": merge_numbers}}
// after
schema = {"numbers": {"type": list, "handler": merge_numbers}}
Defensive patterns

Strategy: validation

Validate before calling

def schema_has_types(schema):
    return all(isinstance(d, dict) and "type" in d for d in schema.values())

Type guard

def is_valid_schema_entry(entry) -> bool:
    return isinstance(entry, dict) and "type" in entry and isinstance(entry["type"], type)

Try / catch

try:
    schema = StateSchema(my_schema)
except ValueError as e:
    if "missing a 'type' entry" in str(e):
        key = str(e).split("'")[1]
        my_schema[key]["type"] = default_types[key]
    else:
        raise

Prevention

When it happens

Trigger: Constructing StateSchema (directly or via Agent state_schema) with an entry like {"param": {"handler": my_handler}} that omits 'type'.

Common situations: Hand-written schema dicts where a key was given only a handler, typos like 'types' instead of 'type', or programmatically built schemas missing a branch.

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 deepset-ai/haystack@e318778c9b (2026-08-30). Data as JSON: /api/errors/be435f700b7267d6. Report an issue: GitHub.