roboflow/supervision · error · ValueError

Cannot merge CompactMask objects with different image shapes

Error message

Cannot merge CompactMask objects with different image shapes: {sorted(compact_image_shapes)}

What it means

Error "Cannot merge CompactMask objects with different image shapes: {sorted(compact_image_shapes)}" thrown in roboflow/supervision.

Source

Thrown at src/supervision/detection/core.py:2458

            masks = [d.mask for d in detections_list]
            if all(m is None for m in masks):
                return None
            if any(m is None for m in masks):
                raise ValueError("All or none of the 'mask' fields must be None")
            if all(isinstance(m, CompactMask) for m in masks):
                return CompactMask.merge(cast(list[CompactMask], masks))
            if all(not isinstance(m, CompactMask) for m in masks):
                # All-dense: preserve backward-compatible dense stacking.
                return cast(
                    npt.NDArray[np.generic], np.vstack([np.asarray(m) for m in masks])
                )
            # Mixed dense and CompactMask: convert dense masks to CompactMask to
            # avoid materialising a full (N, H, W) stack.
            compact_image_shapes = {
                m.image_shape for m in masks if isinstance(m, CompactMask)
            }
            if len(compact_image_shapes) != 1:
                raise ValueError(
                    "Cannot merge CompactMask objects with different image shapes: "
                    f"{sorted(compact_image_shapes)}"
                )
            image_shape: tuple[int, int] = next(iter(compact_image_shapes))
            compact_list: list[CompactMask] = []
            for d, m in zip(detections_list, masks):
                if isinstance(m, CompactMask):
                    compact_list.append(m)
                else:
                    dense = np.asarray(m, dtype=bool)
                    if dense.shape[1:] != image_shape:
                        raise ValueError(
                            f"Dense mask shape {dense.shape[1:]} does not match "
                            f"CompactMask image_shape {image_shape}."
                        )
                    compact_list.append(
                        CompactMask.from_dense(dense, d.xyxy, image_shape)
                    )

View on GitHub (pinned to 7f254d9784)

Solutions

1. Only merge CompactMask objects that share the same image_shape; check cm._image_shape for each before merging.
2. If the masks come from images of different sizes, resize or pad them to a common image_shape first.

When it happens

Trigger: Thrown at src/supervision/detection/core.py:2458 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of roboflow/supervision@7f254d9784 (2026-08-15). Data as JSON: /api/errors/84629c1bacb82019. Report an issue: GitHub.