C-Achard · Oct 23, 2026 · Sep 8, 2026 · Sep 8, 2026 · Sep 8, 2026 · Sep 9, 2026
diff --git a/deeplabcut/pose_estimation_pytorch/apis/videos.py b/deeplabcut/pose_estimation_pytorch/apis/videos.py
@@ -42,6 +42,7 @@
     TopDownDynamicCropper,
 )
 from deeplabcut.pose_estimation_pytorch.runners.inference import InferenceConfig
+from deeplabcut.pose_estimation_pytorch.runners.shelving import frame_key_width
 from deeplabcut.pose_estimation_pytorch.task import Task
 from deeplabcut.refine_training_dataset.stitch import stitch_tracklets
 from deeplabcut.utils import VideoReader, auxiliaryfunctions
@@ -228,15 +229,23 @@ def video_inference(
     if shelf_writer is not None:
         shelf_writer.close()
 
-    if shelf_writer is None and len(predictions) != n_frames:
+    if shelf_writer is None:
         tip_url = "https://deeplabcut.github.io/DeepLabCut/docs/recipes/io.html"
         header = "#tips-on-video-re-encoding-and-preprocessing"
-        logging.warning(
-            f"The video metadata indicates that there {n_frames} in the video, but "
-            f"only {len(predictions)} were able to be processed. This can happen if "
-            "the video is corrupted. You can try to fix the issue by re-encoding your "
-            f"video (tips on how to do that: {tip_url}{header})"
+        reencoding_tip = (
+            "This can happen if the video is corrupted. You can try to fix the issue "
+            f"by re-encoding your video (tips on how to do that: {tip_url}{header})"
         )
+        if len(predictions) == 0:
+            logging.warning(
+                f"No predictions were produced for {video.video_path}: the video could not be read. {reencoding_tip}"
+            )
+        elif len(predictions) != n_frames:
+            logging.warning(
+                f"The video metadata indicates that there are {n_frames} frames in "
+                f"the video, but only {len(predictions)} were able to be processed. "
+                f"{reencoding_tip}"
+            )
 
     return predictions
 
@@ -280,6 +289,9 @@ def analyze_videos(
     The index of the trained network is specified by parameters in the config file
     (in particular the variable 'snapshot_index').
 
+    Frames in which no animal is detected are kept in the outputs, with placeholder
+    values (-1). Videos from which no frame can be read are skipped with a warning.
+
     Args:
         config: full path of the config.yaml file for the project
         videos: a str (or list of strings) containing the full paths to videos for
@@ -542,6 +554,7 @@ def analyze_videos(
     # Reading video and init variables
     videos = collect_video_paths(videos, extensions=video_extensions, shuffle=in_random_order)
     h5_files_created = False  # Track if any .h5 files were created
+    skipped_videos = []  # Videos from which no frame could be read
 
     for video in videos:
         if destfolder is None:
@@ -582,6 +595,13 @@ def analyze_videos(
                 show_gpu_memory=show_gpu_memory,
             )
             runtime.append(time.time())
+
+            num_predicted = len(predictions) if shelf_writer is None else shelf_writer.frames_written
+            if num_predicted == 0:
+                logging.warning(f"Skipping {video}: no frames could be read, so no results are written.")
+                skipped_videos.append(video)
+                continue
+
             metadata = _generate_metadata(
                 cfg=loader.project_cfg,
                 pytorch_config=loader.model_cfg,
@@ -656,7 +676,7 @@ def analyze_videos(
                         ctd_predictions.append(dict(bodyparts=pose))
 
                     create_df_from_prediction(
-                        predictions=predictions,
+                        predictions=ctd_predictions,
                         multi_animal=multi_animal,
                         model_cfg=loader.model_cfg,
                         dlc_scorer=dlc_scorer,
@@ -708,6 +728,14 @@ def analyze_videos(
             "ensure that the video inference and output generation are correct.\n"
         )
 
+    if skipped_videos:
+        logging.warning(
+            f"{len(skipped_videos)} of {len(videos)} video(s) could not be read; no results were written: "
+            f"{', '.join(str(v) for v in skipped_videos)}. Re-encoding these videos may "
+            "help (https://deeplabcut.github.io/DeepLabCut/docs/recipes/io.html"
+            "#tips-on-video-re-encoding-and-preprocessing)."
+        )
+
     return dlc_scorer
 
 
@@ -720,10 +748,8 @@ def create_df_from_prediction(
     output_prefix: str | Path,
     save_as_csv: bool = False,
 ) -> pd.DataFrame:
-    pred_bodyparts = np.stack([p["bodyparts"][..., :3] for p in predictions])
-    pred_unique_bodyparts = None
-    if len(predictions) > 0 and "unique_bodyparts" in predictions[0]:
-        pred_unique_bodyparts = np.stack([p["unique_bodyparts"] for p in predictions])
+    if not predictions:
+        raise ValueError("Cannot create a results DataFrame from an empty predictions list.")
 
     output_h5 = Path(output_path) / f"{output_prefix}.h5"
     output_pkl = Path(output_path) / f"{output_prefix}_full.pickle"
@@ -733,6 +759,11 @@ def create_df_from_prediction(
     individuals = model_cfg["metadata"]["individuals"]
     n_individuals = len(individuals)
 
+    pred_bodyparts = np.stack([p["bodyparts"][..., :3] for p in predictions])
+    pred_unique_bodyparts = None
+    if "unique_bodyparts" in predictions[0]:
+        pred_unique_bodyparts = np.stack([p["unique_bodyparts"] for p in predictions])
+
     print(f"Saving results in {output_h5} and {output_pkl}")
     coords = ["x", "y", "likelihood"]
     cols = [[dlc_scorer], bodyparts, coords]
@@ -743,6 +774,7 @@ def create_df_from_prediction(
         cols_names.insert(1, "individuals")
 
     results_df_index = pd.MultiIndex.from_product(cols, names=cols_names)
+
     pred_bodyparts = pred_bodyparts[:, :n_individuals]
     df = pd.DataFrame(
         pred_bodyparts.reshape((len(pred_bodyparts), -1)),
@@ -887,7 +919,7 @@ def _generate_output_data(
     pose_config: dict,
     predictions: list[dict[str, np.ndarray]],
 ) -> dict:
-    str_width = int(np.ceil(np.log10(len(predictions))))
+    str_width = frame_key_width(len(predictions))
     output = {
         "metadata": {
             "nms radius": pose_config.get("nmsradius"),

diff --git a/deeplabcut/pose_estimation_pytorch/modelzoo/fmpose_3d/inference.py b/deeplabcut/pose_estimation_pytorch/modelzoo/fmpose_3d/inference.py
@@ -192,6 +192,9 @@ def _process_batch(
         if batch:
             _process_batch(batch)
 
+        if not predictions_2d:
+            raise RuntimeError(f"No pose predictions were made for video {video_path}: no frames could be read.")
+
         output_prefix = f"{Path(video_path).stem}_{dlc_scorer}"
         output_h5 = dest_folder / f"{output_prefix}.h5"
 

diff --git a/deeplabcut/pose_estimation_pytorch/runners/inference.py b/deeplabcut/pose_estimation_pytorch/runners/inference.py
@@ -267,6 +267,11 @@ def _async_inference(
                 # propagate any exception from the producer immediately
                 if self._exception is not None:
                     raise self._exception
+            # emit images with an available prediction,
+            # even if no detections were made (which does not produce a queue item)
+            # unless the producer failed, as its exception is raised below
+            if self._exception is None:
+                results.extend(self._extract_results(shelf_writer))
 
         except BaseException as e:  # catches KeyboardInterrupt, SystemExit, etc.
             # tell producer to quit

diff --git a/deeplabcut/pose_estimation_pytorch/runners/shelving.py b/deeplabcut/pose_estimation_pytorch/runners/shelving.py
@@ -73,6 +73,23 @@ def __getitem__(self, item: str) -> dict:
         return self._db[item]
 
 
+def frame_key_width(num_frames: int | None, default: int = 5) -> int:
+    """Returns the zero-fill width for frame keys in a full-data dict.
+
+    Args:
+        num_frames: The number of frames in the video, if known.
+        default: The width to use when the number of frames is unknown.
+
+    Returns:
+        The number of leading zeros to pad frame indices with.
+    """
+    if num_frames is None:
+        return default
+    if num_frames <= 1:
+        return 1
+    return int(np.ceil(np.log10(num_frames)))
+
+
 class ShelfWriter(ShelfManager):
     """Writes data to a shelf on-the-fly during video analysis.
 
@@ -93,9 +110,12 @@ def __init__(self, pose_cfg: dict, filepath: str | Path, num_frames: int | None
         self._num_frames = num_frames
         self._frame_index = 0
 
-        self._str_width = 5
-        if num_frames is not None:
-            self._str_width = int(np.ceil(np.log10(num_frames)))
+        self._str_width = frame_key_width(num_frames)
+
+    @property
+    def frames_written(self) -> int:
+        """The number of frames written to the shelf since it was last opened."""
+        return self._frame_index
 
     def add_prediction(
         self,
@@ -146,8 +166,9 @@ def add_prediction(
 
     def close(self) -> None:
         """Closes the shelf and writes the updated metadata."""
-        if self._open and self._frame_index > 0:
-            # Write updated metadata to shelf (top-level indexing required for shelve)
+        if self._open:
+            # Write updated metadata to shelf (top-level indexing required for shelve),
+            # also when no frame was written so readers don't look for missing frames
             metadata = self._db["metadata"]
             metadata["nframes"] = self._frame_index
             self._db["metadata"] = metadata