langchain-ai/deepagents · error · ValueError

response_schema exceeds maximum nesting depth of {_SCHEMA_MA

Error message

response_schema exceeds maximum nesting depth of {_SCHEMA_MAX_DEPTH}

What it means

During `response_schema` validation, the recursive `_check` walker enforces `_SCHEMA_MAX_DEPTH` on nesting. A schema nested deeper than the limit raises `ValueError`, preventing pathological or accidental deep nesting that would blow up prompts or provider limits.

Source

Thrown at libs/partners/quickjs/langchain_quickjs/_subagent.py:290

    return output


def _validate_response_schema(schema: dict[str, Any]) -> None:
    """Reject schemas that exceed size, depth, or property-count limits."""
    serialized = json.dumps(schema)
    if len(serialized) > _SCHEMA_MAX_BYTES:
        msg = (
            f"response_schema exceeds {_SCHEMA_MAX_BYTES}"
            f" byte limit ({len(serialized)} bytes)"
        )
        raise ValueError(msg)

    def _check(node: dict[str, Any], depth: int, prop_count: list[int]) -> None:
        if depth > _SCHEMA_MAX_DEPTH:
            msg = (
                f"response_schema exceeds maximum nesting depth of {_SCHEMA_MAX_DEPTH}"
            )
            raise ValueError(msg)
        props = node.get("properties")
        if isinstance(props, dict):
            prop_count[0] += len(props)
            if prop_count[0] > _SCHEMA_MAX_PROPERTIES:
                msg = (
                    "response_schema exceeds maximum of"
                    f" {_SCHEMA_MAX_PROPERTIES} properties"
                )
                raise ValueError(msg)
            for value in props.values():
                if isinstance(value, dict):
                    _check(value, depth + 1, prop_count)
        items = node.get("items")
        if isinstance(items, dict):
            _check(items, depth + 1, prop_count)

    _check(schema, 0, [0])

View on GitHub (pinned to a1af029e6e)

Solutions

1. Flatten the schema — replace deep nesting with flatter objects or string/JSON-encoded fields.
2. Cap the depth when programmatically generating the schema.
3. Describe only the shallow part of the payload you need and let the model return the rest as text.
4. Check `_SCHEMA_MAX_DEPTH` for the exact allowed depth before building large schemas.

Example fix

// before
schema = {"type":"object","properties":{"a":{"properties":{"b":{"properties":{"c":{ ... 12 levels ... }}}}}}}

// after
schema = {"type":"object","properties":{"payload_json":{"type":"string","description":"JSON-encoded nested result"}}}

def schema_depth(node, d=0):
    m = d
    for k in ("properties", "items"):
        child = node.get(k)
        if isinstance(child, dict):
            kids = child.values() if k == "properties" else [child]
            for c in kids:
                if isinstance(c, dict):
                    m = max(m, schema_depth(c, d + 1))
    return m
assert schema_depth(schema) <= _SCHEMA_MAX_DEPTH, "schema too deeply nested"

try:
    task(prompt=prompt, response_schema=schema)
except ValueError as e:
    if "nesting depth" in str(e):
        task(prompt=prompt, response_schema=flatten_schema(schema))

When it happens

Trigger: Passing a `response_schema` whose `properties`/`items` chains exceed `_SCHEMA_MAX_DEPTH` levels to `task()`; recursively defined or self-referential schema fragments expanded too far.

Common situations: Generating schemas from deeply nested Python/TypeScript types (e.g. nested dicts of dicts of dicts); transpiling ORM or GraphQL type trees into JSON Schema without flattening.

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

• response_schema exceeds {_SCHEMA_MAX_BYTES} byte limit ({len
• response_schema exceeds maximum of {_SCHEMA_MAX_PROPERTIES}
• Could not parse embedded resource block. Block expected eith
• {question_type} question {question_text!r} must not define '
• Unknown external event kind: {self.kind!r}

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/bf471323ba1c24a7. Report an issue: GitHub.