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
@@ -228,7 +228,13 @@ 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 and len(predictions) == 0 and n_frames > 0:
+        logging.warning(
+            "No predictions were produced for this video. This can happen if no "
+            "animals were detected in any frame. If that is unexpected, check "
+            "model performance and verify that the video can be read correctly."
+        )
+    elif shelf_writer is None and len(predictions) != n_frames:
         tip_url = "https://deeplabcut.github.io/DeepLabCut/docs/recipes/io.html"
         header = "#tips-on-video-re-encoding-and-preprocessing"
         logging.warning(
@@ -718,11 +724,6 @@ 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])
-
     output_h5 = Path(output_path) / f"{output_prefix}.h5"
     output_pkl = Path(output_path) / f"{output_prefix}_full.pickle"
 
@@ -741,6 +742,18 @@ def create_df_from_prediction(
         cols_names.insert(1, "individuals")
 
     results_df_index = pd.MultiIndex.from_product(cols, names=cols_names)
+    if not predictions:
+        df = pd.DataFrame(index=range(0), columns=results_df_index)
+        df.to_hdf(output_h5, key="df_with_missing", format="table", mode="w")
+        if save_as_csv:
+            df.to_csv(output_h5.with_suffix(".csv"))
+        return df
+
+    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])
+
     pred_bodyparts = pred_bodyparts[:, :n_individuals]
     df = pd.DataFrame(
         pred_bodyparts.reshape((len(pred_bodyparts), -1)),
@@ -881,11 +894,18 @@ def _generate_metadata(
     return {"data": metadata}
 
 
+def _frame_key_width(num_frames: int) -> int:
+    """Returns the zero-fill width for frame keys."""
+    if num_frames <= 1:
+        return 1
+    return int(np.ceil(np.log10(num_frames)))
+
+
 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/tests/pose_estimation_pytorch/apis/test_videos.py b/tests/pose_estimation_pytorch/apis/test_videos.py
@@ -0,0 +1,87 @@
+from pathlib import Path
+from unittest.mock import Mock
+
+import pandas as pd
+
+import deeplabcut.pose_estimation_pytorch.apis.videos as videos
+
+POSE_CFG = {
+    "all_joints": [[0], [1], [2]],
+    "all_joints_names": ["snout", "leftear", "rightear"],
+    "nmsradius": 5,
+    "minconfidence": 0.1,
+    "sigma": 1,
+}
+
+
+def test_generate_output_data_handles_empty_predictions():
+    output = videos._generate_output_data(POSE_CFG, [])
+
+    assert output == {
+        "metadata": {
+            "nms radius": 5,
+            "minimal confidence": 0.1,
+            "sigma": 1,
+            "PAFgraph": None,
+            "PAFinds": [],
+            "all_joints": [[0], [1], [2]],
+            "all_joints_names": ["snout", "leftear", "rightear"],
+            "nframes": 0,
+            "key_str_width": 1,
+        }
+    }
+
+
+def test_create_df_from_prediction_handles_empty_predictions(monkeypatch, tmp_path):
+    writes: list[tuple[Path, str, str, str]] = []
+
+    def _fake_to_hdf(self, path_or_buf, key, format, mode):
+        writes.append((Path(path_or_buf), key, format, mode))
+
+    monkeypatch.setattr(pd.DataFrame, "to_hdf", _fake_to_hdf)
+
+    df = videos.create_df_from_prediction(
+        predictions=[],
+        dlc_scorer="DLC_test",
+        multi_animal=False,
+        model_cfg={
+            "metadata": {
+                "bodyparts": ["snout", "leftear", "rightear"],
+                "unique_bodyparts": [],
+                "individuals": ["animal_0"],
+            }
+        },
+        output_path=tmp_path,
+        output_prefix="video",
+        save_as_csv=False,
+    )
+
+    assert df.empty
+    assert list(df.columns.names) == ["scorer", "bodyparts", "coords"]
+    assert writes == [(tmp_path / "video.h5", "df_with_missing", "table", "w")]
+
+
+def test_video_inference_warns_distinctly_for_zero_predictions(monkeypatch, caplog):
+    class FakeVideoIterator:
+        def __init__(self, video_path, cropping=None):
+            self.video_path = video_path
+            self.fps = 25
+            self.dimensions = (640, 480)
+
+        def get_n_frames(self, robust=False):
+            return 3
+
+        def __iter__(self):
+            return iter(())
+
+    monkeypatch.setattr(videos, "VideoIterator", FakeVideoIterator)
+    pose_runner = Mock()
+    pose_runner.batch_size = 2
+    pose_runner.inference.return_value = []
+
+    with caplog.at_level("WARNING"):
+        predictions = videos.video_inference("video.mp4", pose_runner)
+
+    assert predictions == []
+    assert "No predictions were produced for this video." in caplog.text
+    assert "video is corrupted" not in caplog.text