keras-team/keras · error · ValueError

compute_iou() expects boxes1 to be batched, or to be unbatch

Error message

compute_iou() expects boxes1 to be batched, or to be unbatched. Received len(boxes1.shape)={boxes1_rank}, len(boxes2.shape)={boxes2_rank}. Expected either len(boxes1.shape)=2 AND or len(boxes1.shape)=3.

What it means

compute_iou requires boxes1 to have rank 2 (unbatched, shape (num_boxes, 4)) or rank 3 (batched, shape (batch, num_boxes, 4)). If the first argument has any other rank - rank 1 (a flat vector of 4 numbers), rank 4, or a nested list whose shape ops cannot interpret as 2D/3D - this ValueError is raised before any IoU math.

Source

Thrown at keras/src/layers/preprocessing/image_preprocessing/bounding_boxes/iou.py:105

        use_masking: whether masking will be applied. This will mask all
            `boxes1` or `boxes2` that have values less than 0 in all its 4
            dimensions. Default to `False`.
        mask_val: int to mask those returned IOUs if the masking is True,
            defaults to -1.
        image_shape: `Tuple[int]`. The shape of the image (height, width, 3).
            When using relative bounding box format for `box_format` the
            `image_shape` is used for normalization.

    Returns:
        iou_lookup_table: a vector containing the pairwise ious of boxes1 and
            boxes2.
    """  # noqa: E501

    boxes1_rank = len(ops.shape(boxes1))
    boxes2_rank = len(ops.shape(boxes2))

    if boxes1_rank not in [2, 3]:
        raise ValueError(
            "compute_iou() expects boxes1 to be batched, or to be unbatched. "
            f"Received len(boxes1.shape)={boxes1_rank}, "
            f"len(boxes2.shape)={boxes2_rank}. Expected either "
            "len(boxes1.shape)=2 AND or len(boxes1.shape)=3."
        )
    if boxes2_rank not in [2, 3]:
        raise ValueError(
            "compute_iou() expects boxes2 to be batched, or to be unbatched. "
            f"Received len(boxes1.shape)={boxes1_rank}, "
            f"len(boxes2.shape)={boxes2_rank}. Expected either "
            "len(boxes2.shape)=2 AND or len(boxes2.shape)=3."
        )

    target_format = "yxyx"
    if "rel" in bounding_box_format and image_shape is None:
        raise ValueError(
            "When using relative bounding box formats (e.g. `rel_yxyx`) "
            "the `image_shape` argument must be provided."

View on GitHub (pinned to 7a34a03db6)

Solutions

1. Reshape single boxes to (1, 4), e.g. ops.expand_dims(box, axis=0) or [box].
2. Squeeze spurious leading/trailing dims so boxes1 is rank 2 or 3 with last dim 4.
3. For batched inputs keep shape (batch, N, 4).

Example fix

# before
iou = compute_iou([0.0, 0.0, 1.0, 1.0], boxes)
# after
iou = compute_iou([[0.0, 0.0, 1.0, 1.0]], boxes)

boxes1 = ops.convert_to_tensor(boxes1)
assert len(ops.shape(boxes1)) in (2, 3), f"boxes1 rank {len(ops.shape(boxes1))} not in (2,3)"

def boxes_have_valid_rank(t):
    return len(ops.shape(ops.convert_to_tensor(t))) in (2, 3)

When it happens

Trigger: Passing a single box as [0,0,1,1] (rank 1) instead of [[0,0,1,1]]; passing one-hot-encoded boxes of rank 4; passing a nested list with inconsistent depths.

Common situations: Computing IoU for a single predicted box; feeding boxes straight from a model output with an extra leading dimension without squeezing.

Related errors

• compute_iou() expects boxes2 to be batched, or to be unbatch
• When using relative bounding box formats (e.g. `rel_yxyx`) t
• Architecture configuration does not match {weights_name} var
• `height` and `width` must be set if `format='xyxy'`.
• `variance` must be length 4, got {variance}

AI-assisted analysis of keras-team/keras@7a34a03db6 (2026-08-25). Data as JSON: /api/errors/7640a634070136d9. Report an issue: GitHub.