roboflow/supervision · error · ValueError

COCO RLE counts must be one-dimensional.

Error message

COCO RLE counts must be one-dimensional.

What it means

Raised while parsing COCO RLE (Run-Length Encoding) mask counts inside CompactMask.from_coco_rle. After converting the counts payload to an int32 NumPy array, the code requires it to be strictly one-dimensional. A 2-D counts array (e.g. a list of lists) cannot represent the alternating run lengths of an RLE stream, so it is rejected before decoding.

Source

Thrown at src/supervision/detection/compact_mask.py:409

            decoded_counts = _delta_decode(_base48_decode(counts))
            counts_arr = np.array(decoded_counts, dtype=np.int32)
        else:
            # Convert to int64 first, then range-check against int32 bounds before
            # narrowing. A direct int32 cast wraps silently on some numpy versions
            # and raises on others; this makes overflow detection deterministic.
            counts_arr64 = np.asarray(counts, dtype=np.int64)
            int32_info = np.iinfo(np.int32)
            if counts_arr64.size and (
                counts_arr64.max() > int32_info.max
                or counts_arr64.min() < int32_info.min
            ):
                raise ValueError("COCO RLE counts exceed int32 range.")
            counts_arr = counts_arr64.astype(np.int32)
    except (TypeError, ValueError, OverflowError) as exc:
        raise ValueError("Invalid COCO RLE counts.") from exc

    if counts_arr.ndim != 1:
        raise ValueError("COCO RLE counts must be one-dimensional.")
    if counts_arr.size == 0:
        raise ValueError("COCO RLE counts cannot be empty.")
    if np.any(counts_arr < 0):
        raise ValueError("COCO RLE counts must be non-negative.")
    return counts_arr


def _rle_resize(
    rle: npt.NDArray[np.int32],
    crop_h: int,
    crop_w: int,
    new_crop_h: int,
    new_crop_w: int,
) -> npt.NDArray[np.int32]:
    """Resize an F-order RLE-encoded crop via nearest-neighbour resampling.

    Manipulates run lengths directly without decoding to a full 2D boolean
    array.  Delegates to :func:`_rle_split_cols`, :func:`_rle_scale_col`,

View on GitHub (pinned to 7f254d9784)

Solutions

1. Inspect the counts payload you pass and flatten it to a 1-D sequence: np.asarray(counts).reshape(-1) or [c for run in counts for c in run] only if nesting was accidental.
2. If counts came from pycocotools, use the uncompressed form (list of ints) or decode the compressed ASCII string first instead of wrapping it.
3. Verify with np.asarray(rle['counts']).ndim == 1 before calling from_coco_rle.

Example fix

# before
rles = [{"size": [4, 4], "counts": [[0, 2, 2, 2, 10]]}]

# after
rles = [{"size": [4, 4], "counts": [0, 2, 2, 2, 10]}]

import numpy as np

def rle_counts_ok(counts) -> bool:
    try:
        arr = np.asarray(counts, dtype=np.int64)
    except (TypeError, ValueError, OverflowError):
        return False
    return arr.ndim == 1 and arr.size > 0 and (arr >= 0).all()

def is_flat_int_sequence(counts) -> bool:
    return isinstance(counts, (list, tuple)) and all(
        isinstance(c, int) and not isinstance(c, bool) for c in counts
    )

try:
    cm = sv.CompactMask.from_coco_rle(rles, xyxy, image_shape=shape)
except ValueError as e:
    if "one-dimensional" in str(e):
        counts = np.asarray(rle["counts"]).reshape(-1).tolist()  # only if nesting was accidental
    else:
        raise

When it happens

Trigger: Calling CompactMask.from_coco_rle (directly or via a COCO dataset loader) with rle['counts'] shaped like [[0,2,2],[2,10]] or np.array([[...]]) — any nested/2-D structure instead of a flat sequence of integers.

Common situations: Hand-built RLE payloads where counts was accidentally wrapped in an extra list; JSON produced by a custom encoder that nested the counts; passing a decoded-then-reshaped array; mixing up the COCO compressed-string counts with a wrongly deserialized list of lists.

Related errors

• COCO RLE counts cannot be empty.
• COCO RLE counts must be non-negative.
• Invalid COCO RLE counts.
• image_shape must contain positive height and width.
• The sum of COCO RLE counts must match the image area.

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