WZMIAOMIAO/deep-learning-for-image-processing · error · ValueError

No ground-truth boxes available for one of the images during

Error message

No ground-truth boxes available for one of the images during training

What it means

Matcher.__call__ builds an IoU match_quality_matrix of shape (num_gt, num_proposals). If it is empty because there are zero ground-truth boxes (shape[0] == 0) during training, matching is impossible, so it raises this ValueError. The library deliberately rejects empty targets during training rather than silently producing garbage losses.

Source

Thrown at pytorch_object_detection/mask_rcnn/network_files/det_utils.py:317

        self.allow_low_quality_matches = allow_low_quality_matches

    def __call__(self, match_quality_matrix):
        """
        计算anchors与每个gtboxes匹配的iou最大值，并记录索引，
        iou<low_threshold索引值为-1， low_threshold<=iou<high_threshold索引值为-2
        Args:
            match_quality_matrix (Tensor[float]): an MxN tensor, containing the
            pairwise quality between M ground-truth elements and N predicted elements.

        Returns:
            matches (Tensor[int64]): an N tensor where N[i] is a matched gt in
            [0, M - 1] or a negative value indicating that prediction i could not
            be matched.
        """
        if match_quality_matrix.numel() == 0:
            # empty targets or proposals not supported during training
            if match_quality_matrix.shape[0] == 0:
                raise ValueError(
                    "No ground-truth boxes available for one of the images "
                    "during training")
            else:
                raise ValueError(
                    "No proposal boxes available for one of the images "
                    "during training")

        # match_quality_matrix is M (gt) x N (predicted)
        # Max over gt elements (dim 0) to find best gt candidate for each prediction
        # M x N 的每一列代表一个anchors与所有gt的匹配iou值
        # matched_vals代表每列的最大值，即每个anchors与所有gt匹配的最大iou值
        # matches对应最大值所在的索引
        matched_vals, matches = match_quality_matrix.max(dim=0)  # the dimension to reduce.
        if self.allow_low_quality_matches:
            all_matches = matches.clone()
        else:
            all_matches = None

View on GitHub (pinned to 1ec3fe6f37)

Solutions

  1. Filter out images with zero ground-truth boxes from the training set or skip them in the dataset __getitem__/collate
  2. If keeping empty images is required, add dummy/background handling or synthetic boxes as torchvision does for empty targets
  3. Check annotation pipeline: verify targets['boxes'] is non-empty for every image in the training batch

Example fix

// before
for images, targets in train_loader:  # some targets['boxes'].shape == (0, 4)
    loss = model(images, targets)
// after
targets = [t for t in targets if t['boxes'].shape[0] > 0]
images = [im for im, t in zip(images, targets_placeholder) if t['boxes'].shape[0] > 0]
loss = model(images, targets)
Defensive patterns

Strategy: validation

Validate before calling

for t in targets:
    assert isinstance(t['boxes'], torch.Tensor) and t['boxes'].shape[0] > 0, f"image has no gt boxes: {t.get('image_id')}"

Try / catch

try:
    losses = model(images, targets)
except ValueError as e:
    if 'No ground-truth boxes' in str(e):
        log.warning('dropping batch with empty targets'); continue
    raise

Prevention

When it happens

Trigger: Training (model.train()) an RPN/ROI heads where one image's target dict has an empty 'boxes' tensor (or a dataset image with no annotations filtered into the batch), so match_quality_matrix has 0 rows.

Common situations: Datasets containing background-only images with no annotation boxes; dataloader not filtering empty-annotation samples; label files corrupted or empty; training Mask R-CNN/Faster R-CNN on datasets where some images legitimately have no objects.

Related errors

AI-assisted analysis of WZMIAOMIAO/deep-learning-for-image-processing@1ec3fe6f37 (2026-08-30). Data as JSON: /api/errors/bb33e6d9a14458c5. Report an issue: GitHub.