Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

docker compose up hangs at Pulling fs layer or Downloading

Errora3ed95caeb02: Pulling fs layer

Short 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.

  • Applies to Docker Engine 27, Docker Compose v2, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 df
  2. 2Match what you see, then jump to its fix

    1. 1Several layers show Pulling fs layer or Downloading and none finishes; other downloads on the machine are slowThree parallel downloads are too many for a slow connectionFix
    2. 2df shows the file system holding /var/lib/docker at or near 100%The disk behind Docker's data root is fullFix

What does the error look like?

  • a3ed95caeb02: Pulling fs layer
  • docker 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.json

2Fix

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 docker

3Verify

Pull again and watch layers finish one after the other.

docker compose pull

Confirmed by docs.docker.com

Did this fix it?

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 -v

2Fix

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 prune

3Verify

Free space is back and the pull runs.

df -h /var/lib/docker
docker compose pull

Confirmed by docs.docker.com

Did this fix it?

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.