Fix cache verify incorrectly reporting folders as missing files (#3707)

The `hf cache verify` command was incorrectly reporting directories
(like `1_Pooling`, `onnx`) as missing files when using `--fail-on-missing-files`.

Root cause: `list_repo_tree` returns both `RepoFile` and `RepoFolder` entries,
but `collect_local_files` only collects files. This mismatch caused folders
to appear in `missing_paths`.

Fix: Filter out `RepoFolder` entries in `verify_repo_checksums`, only keeping
`RepoFile` entries for comparison.

Fixes #3706

Co-authored-by: Alexandre JUAN <a.juan@namirial.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: 3 people

src/huggingface_hub/hf_api.py

@@ -3361,12 +3361,13 @@ def verify_repo_checksums(
         )
         local_by_path = collect_local_files(root)
 
-        # get remote entries
-        remote_by_path: dict[str, Union[RepoFile, RepoFolder]] = {}
+        # get remote entries (only files, not folders)
+        remote_by_path: dict[str, RepoFile] = {}
         for entry in self.list_repo_tree(
             repo_id=repo_id, recursive=True, revision=remote_revision, repo_type=repo_type, token=token
         ):
-            remote_by_path[entry.path] = entry
+            if isinstance(entry, RepoFile):
+                remote_by_path[entry.path] = entry
 
         return verify_maps(
             remote_by_path=remote_by_path,

src/huggingface_hub/utils/_verification.py

@@ -1,15 +1,15 @@
 import re
 from dataclasses import dataclass
 from pathlib import Path
-from typing import TYPE_CHECKING, Literal, Optional, TypedDict, Union
+from typing import TYPE_CHECKING, Literal, Optional, TypedDict
 
 from .. import constants
 from ..file_download import repo_folder_name
 from .sha import git_hash, sha_fileobj
 
 
 if TYPE_CHECKING:
-    from ..hf_api import RepoFile, RepoFolder
+    from ..hf_api import RepoFile
 
 # using fullmatch for clarity and strictness
 _REGEX_COMMIT_HASH = re.compile(r"^[0-9a-f]{40}$")
@@ -91,7 +91,7 @@ def compute_file_hash(path: Path, algorithm: HashAlgo) -> str:
 
 def verify_maps(
     *,
-    remote_by_path: dict[str, Union["RepoFile", "RepoFolder"]],
+    remote_by_path: dict[str, "RepoFile"],
     local_by_path: dict[str, Path],
     revision: str,
     verified_path: Path,

tests/test_verification.py

@@ -6,7 +6,7 @@
 import pytest
 
 import huggingface_hub.utils._verification as verification_module
-from huggingface_hub.hf_api import HfApi
+from huggingface_hub.hf_api import HfApi, RepoFile, RepoFolder
 from huggingface_hub.utils._verification import (
     HashAlgo,
     collect_local_files,
@@ -147,9 +147,42 @@ def test_api_verify_repo_checksums_cache_mode(tmp_path: Path) -> None:
     with patch.object(
         HfApi,
         "list_repo_tree",
-        return_value=[SimpleNamespace(path="file.txt", blob_id=git_hash(content), lfs=None)],
+        return_value=[RepoFile(path="file.txt", oid=git_hash(content), size=len(content), lfs=None)],
     ):
         res = HfApi().verify_repo_checksums(
             repo_id="user/model", repo_type="model", revision=commit, cache_dir=cache_dir, token=None
         )
         assert res.revision == commit and res.checked_count == 1 and not res.mismatches
+
+
+def test_api_verify_repo_checksums_ignores_folders(tmp_path: Path) -> None:
+    """Test that folders returned by list_repo_tree are ignored and not reported as missing files.
+
+    Regression test for https://github.com/huggingface/huggingface_hub/issues/3706
+    """
+    cache_dir = tmp_path
+    commit = "c" * 40
+    storage = cache_dir / "models--user--model"
+    snapshot = storage / "snapshots" / commit
+    snapshot.mkdir(parents=True)
+
+    # Create files inside a nested folder structure
+    content = b"file content"
+    _write(snapshot / "subdir" / "file.txt", content)
+
+    # Mock list_repo_tree to return both a folder and a file (as the real API does)
+    def mock_list_repo_tree(*args, **kwargs):
+        # The real API returns RepoFolder for directories and RepoFile for files
+        yield RepoFolder(path="subdir", oid="tree-oid-123")
+        yield RepoFile(path="subdir/file.txt", oid=git_hash(content), size=len(content), lfs=None)
+
+    with patch.object(HfApi, "list_repo_tree", mock_list_repo_tree):
+        res = HfApi().verify_repo_checksums(
+            repo_id="user/model", repo_type="model", revision=commit, cache_dir=cache_dir, token=None
+        )
+        # The folder should NOT be in missing_paths
+        assert "subdir" not in res.missing_paths
+        assert res.checked_count == 1
+        assert res.mismatches == []
+        assert res.missing_paths == []
+        assert res.extra_paths == []