GitHub Actions cache lookup-only Reports Hit But Downloads Nothing

By Kaveh Alemi·Latchkey

With lookup-only: true the cache action checks whether an entry exists and reports cache-hit, but it deliberately does not download the files - so a later step that expects the cached paths finds them empty.

What this error means

cache-hit is true, yet the cached directory is empty and the build rebuilds everything, because lookup-only restored nothing by design.

- uses: actions/cache@v4
  with:
    path: ~/.cache/build
    key: build-${{ hashFiles('lock') }}
    lookup-only: true   # only checks existence; does not restore files

Common causes

lookup-only skips the download

lookup-only is for deciding whether work is needed (for example, gating an expensive build) without paying to download the cache. It never populates the path.

Treating the hit as if files were restored

A true cache-hit under lookup-only means the entry exists, not that its contents are on disk. Steps that need the files still must restore them.

How to fix it

Restore the files when you need them

Use lookup-only only to gate work; do a real restore where the files are required.

- uses: actions/cache/restore@v4
  with:
    path: ~/.cache/build
    key: build-${{ hashFiles('lock') }}

Use the hit as a signal, not as data

1. Branch on the lookup-only cache-hit to skip rebuilding when an entry already exists.
2. Restore the cache separately in the path that actually consumes the files.
3. Do not assume the directory is populated after a lookup-only hit.

How to prevent it

• Reserve lookup-only for existence checks and gating.
• Restore the cache wherever the files are actually used.
• Document why a lookup-only step does not populate its path.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions