Fix cached_files silently returning stale file on read-only filesystem (EROFS)

[ydshieh]

Problem

When the HF Hub cache is on a read-only filesystem (in some rare CI environments, a pre-populated cache may be mounted read-only, potentially for security reasons), hf_hub_download still contacts the Hub to resolve the latest commit hash. If a newer revision exists, it then tries to write the new snapshot pointer / blob to disk and fails with OSError: [Errno 30] Read-only file system (EROFS).

On the cached_files side, EROFS is not handled: Python only promotes EACCES (errno 13) to its own PermissionError subclass, so the existing isinstance(e, PermissionError) guard catches EACCES but misses EROFS (errno 30), which is a plain OSError. Without this fix, the EROFS error falls through to the stale-cache recovery block, which silently returns the old cached file — even when the Hub has a newer revision.

Fix

Add an explicit elif isinstance(e, OSError) and e.errno == errno.EROFS guard that re-raises the error before the stale-cache recovery block, giving callers a chance to catch it and retry with a writable cache path (our patch in conftest.py).

Why EROFS reaches cached_files but EACCES doesn't

The difference comes down to where the kernel rejects the write:

Method	FS writable?	Rejected at	errno	Python type
chmod 555 / chown root	Yes	DAC permission check	13 (EACCES)	PermissionError (subclass of OSError)
mount -o ro / read-only volume	No	VFS mount flag check	30 (EROFS)	plain OSError

• With chmod/chown, the filesystem is still writable — the kernel reaches the DAC check, finds the user lacks permission on that path, and returns EACCES. Python promotes this to PermissionError, so the existing guard in cached_files catches it.
• With a read-only mount, the kernel rejects the write at the VFS layer (mount flag MS_RDONLY) before any permission check. This returns a plain OSError(errno.EROFS) that Python does not promote to PermissionError, so it slips past the existing guard.

Impact

This changes behaviour only when cached_files is called with a cache directory on a filesystem mounted read-only via mount -o ro (or equivalent kernel-level read-only mount). This is a rare setup — primarily used in our own CI for security/isolation purposes (pre-populated read-only cache volumes). The behaviour change for regular users (writable cache, network errors, permission-bit errors) is zero.

Testing

Verified by:

1. Confirming CI fails (old stale chat_template returned) without this fix: https://github.com/huggingface/transformers/actions/runs/31317535108/job/93255227530
2. Confirming CI passes (new chat_template loaded correctly) with this fix applied: https://github.com/huggingface/transformers/actions/runs/31317927760

[HuggingFaceDocBuilderDev]

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.

[github-actions]

---

CI recap

Dashboard: View test results in Grafana
Latest run: 31319427357:1
Result: success | Jobs: 16 | Tests: 179,409 | Failures: 0 | Duration: 15h 38m