Azure Pipelines Cache@2 Service Transient Timeout (restoreKeys)

By Daniel Zoghalchali·Latchkey

The Cache@2 task talks to the Azure Artifacts cache service. A transient backend timeout on restore or save is distinct from a clean miss: a miss is handled by restoreKeys fallback, while a service timeout is a network blip that usually clears on retry.

What this error means

The cache step errors with a request/upload timeout to the cache service (not a key miss). Re-running the job typically succeeds with no change, which marks it as transient infrastructure rather than a configuration issue.

##[warning]Cache restore failed: Request timeout contacting the cache service.
##[error]Failed to save cache: upload timed out. Please retry.

Common causes

Transient cache backend timeout

A brief slowdown in the Azure Artifacts cache backend times out the restore or save. Nothing is wrong with your key or path - it is a service blip.

Oversized cache amplifying a slow link

A very large cached path increases upload time, making it more likely to exceed the service timeout during a congested window.

How to fix it

Set robust keys with restoreKeys fallback

A stable key plus restoreKeys turns a partial situation into a hit instead of a hard miss, reducing pressure on the backend.

steps:
  - task: Cache@2
    inputs:
      key: 'yarn | "$(Agent.OS)" | yarn.lock'
      restoreKeys: |
        yarn | "$(Agent.OS)"
        yarn
      path: $(YARN_CACHE_FOLDER)

Retry on transient timeouts; trim the cache

A service timeout clears on re-run. Keep the cached path lean so saves stay well under the timeout.

How to prevent it

• Key caches on the lockfile and add restoreKeys for partial hits.
• Cache only expensive-to-rebuild paths to keep size down.
• Treat occasional cache-service timeouts as transient and rely on retry.

Frequently asked questions

Related guides

References

• GitHub Actions documentation