Skip to content

Fix race in _get_version that makes concurrent downloads skip hf_xet - #5102

Merged
hanouticelina merged 2 commits into
huggingface:mainfrom
BramVanroy:fix-get-version-race
Oct 7, 2026
Merged

hanouticelina merged 2 commits into
huggingface:mainfrom
BramVanroy:fix-get-version-race

Conversation

@BramVanroy

@BramVanroy BramVanroy commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

Fixes #5101.

_get_version wrote the placeholder "N/A" into the shared _package_versions cache before it called importlib.metadata.version. A thread that called is_xet_available() during that lookup read the placeholder and took the plain HTTP path, so concurrent hf_hub_download calls in a fresh process could skip hf_xet for part of the files.

The version is now resolved into a local variable and written to the cache once. Concurrent first calls may each do the lookup, but none of them can read a half-written entry. The cache and the return values are otherwise unchanged.

The new test in tests/test_utils_runtime.py replaces importlib.metadata.version with a slow stub and starts 8 threads behind a barrier. On main it fails in 10 of 10 runs, with threads that get "N/A". With this change it passes in 20 of 20 runs.

Checks (Python 3.14, Linux): pytest tests/test_utils_runtime.py, ruff check, ruff format --check. ty check src reports the same 2 diagnostics in cli/_output.py as on main, and none in _runtime.py.


Note

Medium Risk
Changes thread-safety of package availability caching used by is_xet_available() and download routing; fix is small but affects concurrent hub downloads.

Overview
Fixes a race in _get_version where the shared _package_versions cache was updated with a "N/A" placeholder before importlib.metadata.version finished. Concurrent first-time callers (e.g. via is_xet_available() during parallel hf_hub_download) could read that placeholder and treat hf_xet as missing, skipping the Xet download path for some files in a fresh process (#5101).

The lookup now resolves into a local variable and writes the cache once after resolution. Concurrent cold starts may still duplicate metadata lookups, but no thread observes a half-populated entry.

Adds test_get_version_concurrent_first_lookup: eight threads hit _get_version("hf_xet") behind a barrier with a slow mocked importlib.metadata.version, asserting every thread gets the real version instead of "N/A".

Reviewed by Cursor Bugbot for commit c1d2ad1. Bugbot is set up for automated code reviews on this repo. Configure here.

@Ayushdevo Ayushdevo left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

AI-assisted community review at 59c9371, Python 3.12.14. With PYTHONPATH=src, python -m pytest tests/test_utils_runtime.py -q passes 3 tests.

I additionally used threading.Event to hold the metadata lookup before completion and inspected the cache while it was blocked: hf_xet is absent rather than temporarily cached as N/A. Releasing the lookup lets both concurrent callers receive 1.2.3. I also mocked PackageNotFoundError: two sequential calls return cached N/A, with only one metadata lookup. This verifies the installed-package race fix alongside unchanged negative-cache behavior. Concurrent duplicate metadata lookups remain possible, as the PR describes. I did not run real downloads or the full suite.

@hanouticelina hanouticelina left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks a lot for catching and fixing this @BramVanroy!

Comment thread src/huggingface_hub/utils/_runtime.py Resolved
@codecov

codecov Bot commented Oct 7, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 77.53%. Comparing base (1daa48b) to head (c1d2ad1).
⚠️ Report is 776 commits behind head on main.

Additional details and impacted files
@@            Coverage Diff             @@
##             main    #5102      +/-   ##
==========================================
+ Coverage   75.00%   77.53%   +2.52%     
==========================================
  Files         145      177      +32     
  Lines       13978    24831   +10853     
==========================================
+ Hits        10484    19252    +8768     
- Misses       3494     5579    +2085     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@bot-ci-comment

bot-ci-comment Bot commented Oct 7, 2026

Copy link
Copy Markdown

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

@hanouticelina
hanouticelina merged commit 8abbfe5 into huggingface:main Oct 7, 2026
25 of 27 checks passed
@BramVanroy
BramVanroy deleted the fix-get-version-race branch October 8, 2026 04:51
@huggingface-hub-bot

Copy link
Copy Markdown
Contributor

This PR has been shipped as part of the v2.2.0 release.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Concurrent hf_hub_download calls fall back to HTTP because _get_version caches "N/A" during the lookup

3 participants