docker compose up hangs at Pulling fs layer or Downloading
a3ed95caeb02: Pulling fs layerShort answer
The daemon downloads three layers at a time by default. On a weak connection that can stall or time out, so lower the concurrency. Also check free space where Docker stores its data. Look at docker system df and df before you change anything else.
Fix it fast
1Find out which cause you have
Check free space on the Docker data directory and what Docker itself holds.
df -h /var/lib/docker docker system df2Match what you see, then jump to its fix
What does the error look like?
a3ed95caeb02: Pulling fs layerdocker compose up stays on the pull step with no progress
Cause 1 of 2
Three parallel downloads are too many for a slow connection
1Check
The docs say the daemon downloads three layers at a time by default and that low-bandwidth connections may time out. The limit is the max-concurrent-downloads daemon setting.
cat /etc/docker/daemon.json2Fix
Lower the concurrency to one in daemon.json. The setting is read from daemon.json.
# /etc/docker/daemon.json
{ "max-concurrent-downloads": 1 }
sudo systemctl restart docker3Verify
Pull again and watch layers finish one after the other.
docker compose pullConfirmed by docs.docker.com
Cause 2 of 2
The disk behind Docker's data root is full
1Check
Docker keeps images and layers in its data-root, /var/lib/docker by default. docker system df lists the space used by images, containers and volumes and what can be reclaimed.
df -h /var/lib/docker
docker system df -v2Fix
Remove unused data. By default prune keeps volumes; adding --volumes also removes anonymous volumes that no container uses, and that data usually cannot be recovered, so read the list it prints first. Or move data-root to a bigger disk in daemon.json.
docker system prune3Verify
Free space is back and the pull runs.
df -h /var/lib/docker
docker compose pullConfirmed by docs.docker.com
How do I stop it coming back?
- Prune unused images and build cache on a schedule on CI machines.
- Keep Docker's data-root on a disk with room for a few image versions.
- On slow links, keep max-concurrent-downloads low rather than retrying by hand.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Servers
docker pull fails with net/http: TLS handshake timeout from the registry
net/http: TLS handshake timeout
The Docker daemon, not your shell, opens the connection to the registry, and its TLS handshake did not finish in time.
2 causes, each with a fixServers
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fixServers
sam local fails: Running AWS SAM projects locally requires Docker
Cannot connect to the Docker daemon. Is the docker daemon running on this host?
sam local start-api and sam local invoke run your function inside a Docker container, so SAM stops if it cannot talk to Docker.
3 causes, each with a fixServers
dnf fails to download repo metadata in a CentOS 8 Docker build
The same Dockerfile built fine before 2022
CentOS Linux 8 reached end of life on 31 December 2021 and its content left the mirrors.
2 causes, each with a fixServers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
Cypress says the npm package is installed but the binary is missing
Cypress binary is missing after npm install in CI or in a Docker build
The npm package is only a launcher.
3 causes, each with a fix