ComposioHQ/composio · error · JSONSchemaRefResolutionError

JSON Schema nesting too deep to dereference

Error message

JSON Schema nesting too deep to dereference

What it means

dereference_json_schema caught a Python RecursionError while walking the schema — the structure was too deep to traverse even before the internal caps fired. This is a hard stop against interpreter stack exhaustion from pathological nesting.

Source

Thrown at python/composio/utils/json_schema.py:251

            resolved = walk(target, next_refs, chain_depth + 1, node_depth + 1)

            # Shallow-merge sibling keywords next to ``$ref`` (Draft 2020-12:
            # siblings win on collision). Draft 7 ignores them, but the Composio
            # tool surface admits both, so we honor siblings for safety.
            siblings = {key: value for key, value in node.items() if key != "$ref"}
            if not siblings or not _is_mapping(resolved):
                return resolved
            merged = dict(resolved)
            for key, value in siblings.items():
                merged[key] = walk(value, visited_refs, chain_depth, node_depth + 1)
            return merged
        finally:
            visiting.discard(node_id)

    try:
        out = walk(root, frozenset(), 0, 0)
    except RecursionError as exc:  # pragma: no cover - depth cap normally fires first
        raise JSONSchemaRefResolutionError(
            "JSON Schema nesting too deep to dereference"
        ) from exc
    if _is_mapping(out):
        out.pop("$defs", None)
        out.pop("definitions", None)
    return out

View on GitHub (pinned to 64b1b85502)

Solutions

1. Flatten or reject the input schema
2. If you control the runtime and trust the schema, raise sys.setrecursionlimit — but fixing the schema is safer
3. Report legitimate Composio tool schemas that trigger this

import sys
def safe_to_walk(schema):
    return sys.getrecursionlimit() > 1000 and isinstance(schema, dict)

from composio.exceptions import JSONSchemaRefResolutionError
try:
    out = dereference_json_schema(schema)
except JSONSchemaRefResolutionError:
    out = {"type": "object", "additionalProperties": True}  # degrade gracefully

When it happens

Trigger: A schema nested deeply enough that Python's own recursion limit is hit inside walk() before MAX_NODE_DEPTH/MAX_REF_CHAIN_DEPTH trigger (e.g. when sys.setrecursionlimit was lowered, or nesting arrives via branches the caps don't count).

Common situations: Running inside constrained interpreters (low recursion limit, embedded hosts); adversarial or corrupted schema payloads.

Related errors

• Cannot resolve $ref {pointer}
• JSON Schema node depth exceeded cap ({MAX_NODE_DEPTH})
• JSON Schema $ref chain exceeded depth cap ({MAX_REF_CHAIN_DE
• Invalid property type {p_type}: {schema!r}
• JSON Schema exceeds maximum nesting depth of {MAX_NODE_DEPTH

AI-assisted analysis of ComposioHQ/composio@64b1b85502 (2026-08-28). Data as JSON: /api/errors/aa0c8e9a29c5a6ea. Report an issue: GitHub.