Hugging Face "ReadTimeoutError" during model download in CI

The connection to the Hub opened but the download of a large weights file stalled past the read timeout. Model shards are big, so a congested link can outlast the default timeout on one attempt.

What this error means

A download fails or retries with "ReadTimeoutError: HTTPSConnectionPool(host='huggingface.co', ...): Read timed out." while pulling model.safetensors or a shard.

huggingface_hub

urllib3.exceptions.ReadTimeoutError: HTTPSConnectionPool(host='cdn-lfs.huggingface.co',
port=443): Read timed out. (read timeout=10)

Common causes

A large file over a slow or congested link

Multi-gigabyte weights over a busy runner network can exceed the read timeout before the transfer finishes.

A default timeout too short for big shards

The default per-read timeout is fine for metadata but tight for large binary downloads.

How to fix it

Raise the download timeout

Give huggingface_hub more time per read so a slow shard completes.

Terminal

export HF_HUB_DOWNLOAD_TIMEOUT=120
python -c "from huggingface_hub import snapshot_download; snapshot_download('bert-base-uncased')"

Cache downloads to avoid re-fetching

Persist HF_HOME so a file downloaded once is reused and not re-pulled on every run.

.github/workflows/ci.yml

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

How to prevent it

Set a generous HF_HUB_DOWNLOAD_TIMEOUT for large models.
Cache HF_HOME so big files download once.
Prefetch weights in a dedicated step with retries.