Hugging Face offline mode "cannot find the requested files in the cached path" in CI

You enabled offline mode, so HF made no network request, but the requested files are not in HF_HOME. Offline mode only works once the cache is warm; the fix is to populate the cache before switching offline.

What this error means

A load fails with "Cannot find the requested files in the cached path ... and outgoing traffic has been disabled. To enable ... set HF_HUB_OFFLINE=0".

huggingface_hub

OSError: Cannot find the requested files in the cached path at /root/.cache/huggingface/hub
and outgoing traffic has been disabled. To enable model look-ups and downloads online,
set 'HF_HUB_OFFLINE=0' as environment variable.

Common causes

Offline mode with an empty cache

HF_HUB_OFFLINE=1 (or TRANSFORMERS_OFFLINE=1) blocks all fetches, so a model never downloaded before is unavailable.

The restored cache path does not match HF_HOME

The cache was restored to a different directory than HF_HOME points at, so the files are effectively invisible.

How to fix it

Warm the cache online, then go offline

In a prefetch step (online), download the exact models and datasets into HF_HOME.
Cache that directory keyed on the asset list.
Set HF_HUB_OFFLINE=1 for the test job that consumes the warm cache.

Terminal

HF_HOME=$GITHUB_WORKSPACE/.hf-cache python -c "from huggingface_hub import snapshot_download; snapshot_download('bert-base-uncased')"

Point HF_HOME at the restored cache

Ensure the cache action restores to the same HF_HOME the offline job reads.

.github/workflows/ci.yml

- uses: actions/cache@v4
  with:
    path: ${{ github.workspace }}/.hf-cache
    key: hf-${{ hashFiles('models.txt') }}

How to prevent it

Prefetch every model and dataset before enabling offline mode.
Use one HF_HOME path for both the prefetch and the offline job.
Key the cache on the exact asset list so misses are visible.