JuliusBrussee/caveman · error · ValueError

bounded

Error message

bounded

What it means

walk is a custom position-tracking JSON parser used to record string spans. To keep the hand-rolled recursive descent safe it enforces hard bounds: nesting depth of 64 and 65536 total nodes. Exceeding either raises ValueError('bounded') instead of recursing without limit.

Solutions

1. Reduce the nesting depth of the JSON payload before parsing (flatten or restructure)
2. Split oversized documents and parse them in chunks under the 65536-node budget
3. If legitimate payloads are deeper, raise the depth/nodes constants in _google_wire.py deliberately
4. Catch ValueError and treat the payload as unsupported wire format

Example fix

# before
value = parse(deeply_nested_text)  # ValueError: bounded
# after
text = json.dumps(flatten(json.loads(raw), max_depth=32))
value = parse(text)

def within_bounds(text, max_depth=64, max_nodes=65536):
    import json
    def depth(pairs_or_obj):
        if isinstance(pairs_or_obj, dict):
            return 1 + max((depth(v) for v in pairs_or_obj.values()), default=0)
        if isinstance(pairs_or_obj, list):
            return 1 + max((depth(v) for v in pairs_or_obj), default=0)
        return 0
    obj = json.loads(text)
    return depth(obj) <= max_depth

try:
    value = parse(text)
except ValueError as e:
    if str(e) == "bounded":
        log.warning("payload exceeds parser bounds (depth>64 or nodes>65536); rejecting")
        value = None

When it happens

Trigger: Parsing a JSON text whose nesting exceeds 64 levels, or whose total node count exceeds 65536, via the parse() entry point of _google_wire.

Common situations: Feeding deeply machine-generated JSON (e.g. stacked API payloads or serialized traces) into the wire parser; adversarial/malformed inputs designed to blow the stack; re-parsing large accumulated transcript blobs.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• assembly slot content is not JSON-serializable
• colon
• comma
• duplicate
• Agno middleware requires a nonempty native session_id

AI-assisted analysis of JuliusBrussee/caveman@3ee70a1026 (2026-09-20). Data as JSON: /api/errors/38ce23c7462c035e. Report an issue: GitHub.

Appendix: source

Thrown at packages/middleware/python/caveman_middleware/_google_wire.py:19

"""Bounded Google JSON string offsets; untouched serialized text stays exact."""
import json


def parse(text):
    if len(text) > 2 << 20:
        return None
    decoder, strings, index, nodes = json.JSONDecoder(), {}, 0, 0

    def white():
        nonlocal index
        while index < len(text) and text[index] in " \t\r\n":
            index += 1

    def walk(path, depth=0):
        nonlocal index, nodes
        nodes += 1
        if depth > 64 or nodes > 65536:
            raise ValueError("bounded")
        white()
        start = index
        if text[index] == '"':
            value, index = decoder.raw_decode(text, index)
            strings[path] = (start, index, value)
            return value
        if text[index] == "{":
            index += 1
            result = {}
            white()
            if text[index] == "}":
                index += 1
                return result
            while True:
                white()
                key, index = decoder.raw_decode(text, index)
                if type(key) is not str or key in result:
                    raise ValueError("duplicate")

View on GitHub (pinned to 3ee70a1026)