Docker "failed to solve: DeadlineExceeded" (Build Timeout) in CI

By Kaveh Alemi·Latchkey

A build operation blew past its deadline. DeadlineExceeded means a step or a backend call (importing cache, pulling a base image, a download) took longer than the allowed time - usually a slow build, a slow registry, or an unresponsive remote.

What this error means

A build fails with failed to solve: ... context deadline exceeded / DeadlineExceeded, often while pulling a base image, importing cache, or in a long download step.

#5 [internal] load metadata for docker.io/library/node:20
#5 ERROR: failed to solve: failed to fetch ...: context deadline exceeded (Client.Timeout exceeded while awaiting headers)

Common causes

A slow or unresponsive registry/remote

Pulling base-image metadata or cache from a slow registry can exceed the client deadline, surfacing as DeadlineExceeded.

The build step itself is too slow

A heavy compile or a large download that runs past the operation deadline triggers the timeout.

Transient network slowness

A temporarily congested network makes an otherwise-fine fetch exceed its deadline; it often passes on retry.

How to fix it

Cache and speed up the slow operations

Cache base-image metadata and layers so the deadline-prone fetches do less work.

- uses: docker/build-push-action@v6
  with:
    cache-from: type=gha
    cache-to: type=gha,mode=max
    pull: true

Retry transient deadline failures

A DeadlineExceeded from a momentarily slow remote clears on retry; a consistently slow step needs optimization.

How to prevent it

• Cache base images and layers to shrink deadline-prone fetches.
• Pull from a fast/mirrored registry for base images.
• Split very long build steps so none runs near a deadline.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation