Comfy-Org/ComfyUI · error · ValueError

bboxes input must be bounding boxes, elements, or a JSON str

Error message

bboxes input must be bounding boxes, elements, or a JSON string, got {type(data).__name__}

What it means

boxes_from_input only accepts str, dict, or list. Any other top-level type — int, float, tuple (Python-side call, not JSON), None-like objects, or a numpy array — reaches the final isinstance check and raises with the actual type name.

Source

Thrown at comfy_extras/nodes_bounding_boxes.py:254

        return []
    if isinstance(data, str):
        text = data.strip()
        if not text:
            return []
        try:
            data = json.loads(text)
        except (ValueError, TypeError) as exc:
            raise ValueError(f"bboxes string input is not valid JSON: {exc}") from exc
    if isinstance(data, dict):
        if _looks_like_element(data):
            return elements_to_boxes([data], width, height)
        if _looks_like_bbox(data):
            return normalize_incoming_boxes(data)
        raise ValueError(
            "bboxes dict must be a bounding box (x, y, width, height) or an element (with a 'bbox')"
        )
    if not isinstance(data, list):
        raise ValueError(
            "bboxes input must be bounding boxes, elements, or a JSON string, "
            f"got {type(data).__name__}"
        )
    if not data:
        return []
    first = data[0]
    if isinstance(first, list):
        return normalize_incoming_boxes(data)
    if isinstance(first, dict):
        if _looks_like_element(first):
            return elements_to_boxes(data, width, height)
        if _looks_like_bbox(first):
            return normalize_incoming_boxes(data)
        raise ValueError(
            "bboxes items must be bounding boxes (x, y, width, height) or elements (with a 'bbox')"
        )
    raise ValueError(
        f"bboxes list must contain bounding boxes or elements, got {type(first).__name__}"

View on GitHub (pinned to 1c6d8d45b3)

Solutions

1. Convert to a list before calling: list(data) or data.tolist() for numpy arrays
2. Ensure JSON input arrives as a string (it will be parsed) rather than another primitive
3. Match the documented input contract: list, dict, or JSON string only

Example fix

// before
boxes_from_input(((0, 0, 100, 100),), w, h)  # tuple -> raises

// after
boxes_from_input([(0, 0, 100, 100)], w, h)  # or list(((0,0,100,100),))

if isinstance(data, tuple):
    data = list(data)
elif hasattr(data, 'tolist'):
    data = data.tolist()
assert isinstance(data, (str, dict, list))

def is_boxes_input(v) -> bool:
    return isinstance(v, (str, dict, list))

When it happens

Trigger: Programmatically calling the API with a tuple of boxes (isinstance(data, list) is False for tuples); passing a numpy array of coordinates; passing a plain integer/float or an unwrapped tensor.

Common situations: Python callers reusing tuple literals out of habit; converting loaded data via numpy without .tolist(); API boundaries that deserialize JSON to non-list sequences.

Related errors

• Invalid value(s) in transformer_options chroma_radiance_opti
• Unexpected type for duration key, must be str, int or float
• bboxes element is missing a valid 'bbox' [ymin, xmin, ymax,
• bboxes element 'bbox' must contain four numbers
• bboxes string input is not valid JSON: {exc}

AI-assisted analysis of Comfy-Org/ComfyUI@1c6d8d45b3 (2026-08-14). Data as JSON: /api/errors/4f5e7ad4cbb45727. Report an issue: GitHub.