What causes "The channel({channel}) of the img is not in [1, 2, 3, 4]" in opendatalab/MinerU?

Inspect arr.shape before loading; fix the stacking/concatenation axis upstream.

opendatalab/MinerU · error · LoadImageError

The channel({channel}) of the img is not in [1, 2, 3, 4]

Error message

The channel({channel}) of the img is not in [1, 2, 3, 4]

What it means

convert_img handles 3-D arrays only with 1, 2, 3, or 4 channels (gray, gray+alpha, RGB, RGBA conversions to BGR). A 3-D array with any other last dimension (5+, 0) cannot be interpreted as an image and raises LoadImageError naming the offending channel count.

Source

Thrown at mineru/model/table/rec/unet_table/utils.py:131

    def convert_img(self, img: np.ndarray):
        if img.ndim == 2:
            return cv2.cvtColor(img, cv2.COLOR_GRAY2BGR)

        if img.ndim == 3:
            channel = img.shape[2]
            if channel == 1:
                return cv2.cvtColor(img, cv2.COLOR_GRAY2BGR)

            if channel == 2:
                return self.cvt_two_to_three(img)

            if channel == 4:
                return self.cvt_four_to_three(img)

            if channel == 3:
                return cv2.cvtColor(img, cv2.COLOR_RGB2BGR)

            raise LoadImageError(
                f"The channel({channel}) of the img is not in [1, 2, 3, 4]"
            )

        raise LoadImageError(f"The ndim({img.ndim}) of the img is not in [2, 3]")

    @staticmethod
    def cvt_four_to_three(img: np.ndarray) -> np.ndarray:
        """RGBA → BGR"""
        r, g, b, a = cv2.split(img)
        new_img = cv2.merge((b, g, r))

        not_a = cv2.bitwise_not(a)
        not_a = cv2.cvtColor(not_a, cv2.COLOR_GRAY2BGR)

        new_img = cv2.bitwise_and(new_img, new_img, mask=a)
        new_img = cv2.add(new_img, not_a)
        return new_img

View on GitHub (pinned to 4fe4bde114)

Solutions

Inspect arr.shape before loading; fix the stacking/concatenation axis upstream.
Slice to the first 3 channels if extra channels are accidental: img = img[..., :3].
Ensure you pass pixel images (H, W, C) not feature maps.

Example fix

# before
img = np.concatenate([bgr, alpha, extra], axis=2)  # 5 channels
img = loader(img)

# after
img = bgr  # keep (H, W, 3); compose alpha separately
img = loader(img)

Defensive patterns

Strategy: validation

Validate before calling

if img.ndim == 3 and img.shape[2] not in (1, 2, 3, 4):
    img = img[..., :3]  # or raise with context

Type guard

def has_valid_channels(img: np.ndarray) -> bool:
    return img.ndim != 3 or img.shape[2] in (1, 2, 3, 4)

Try / catch

try:
    img = loader(raw)
except LoadImageError as e:
    if 'channel' in str(e):
        img = loader(raw[..., :3])
    else:
        raise

Prevention

Assert arr.shape right after every crop/stack operation.
Prefer cv2.merge over np.concatenate for adding channels.
Never feed feature maps into image loaders.

When it happens

Trigger: Passing multi-spectral arrays (H, W, 5+), preprocessed float batches with a stray leading axis flattened wrongly, or arrays where channel data was concatenated along the wrong axis.

Common situations: Numpy stacking bugs (np.concatenate along axis=2 instead of a new axis), feeding model feature maps instead of images, malformed crops from upstream code.

Related errors

AI-assisted analysis of opendatalab/MinerU@4fe4bde114 (2026-08-14). Data as JSON: /api/errors/46770d05818fc16b. Report an issue: GitHub.