Introduction

When Docker Compose hangs on Downloading or fails with pulling fs layer ... closed, the issue is usually not your docker-compose.yml. The most common causes are unstable network transfer, exhausted disk space, corrupted local layer metadata, aggressive proxy/firewall timeouts, or registry throttling. Because image pulls are layered and resumable, partial failures can leave state that repeatedly breaks future pulls. The fix is a structured cleanup and verification workflow: confirm host resources, clear broken cache safely, and retry with stable network settings.

Understand What fs layer closed Means

Docker pulls each image as independent filesystem layers. If a stream closes unexpectedly, Docker reports the layer as closed and retries. Repeated failures indicate the local engine cannot complete layer assembly.

Useful first checks:

docker info
docker system df
docker compose pull --quiet

Look for warning signs in daemon logs, especially I/O and overlay errors.

# Linux (systemd)
journalctl -u docker --since "30 min ago" | tail -n 200

If you see repeated network resets or storage-driver errors, treat those before repeatedly re-running Compose.

Apply a Safe Recovery Sequence

Start with low-risk cleanup, then escalate only if needed.

1# Stop current stack
2docker compose down
3
4# Remove dangling cache and stopped containers
5docker image prune -f
6docker container prune -f
7
8# Retry pulling
9docker compose pull

If failures persist, clear build cache and unused volumes cautiously:

docker builder prune -af
docker system prune -f

For local development where full cleanup is acceptable, removing all unused images can resolve corrupted layer states quickly.

Network, Registry, and Proxy Stability

Pull failures often come from middleboxes, VPNs, or rate limits. Verify registry reachability and auth.

docker login
curl -I https://registry-1.docker.io/v2/

If your company uses a proxy, configure Docker daemon proxy variables consistently and restart Docker. Also avoid running multiple heavy pulls concurrently on unreliable links.

In CI, prefer pinned image tags and registry mirrors. A local mirror reduces repeated internet pulls and lowers failure probability.

When Storage Driver or Disk Is the Root Cause

Insufficient free disk or inode exhaustion can interrupt layer extraction mid-stream.

df -h
df -i

If disk is tight, expand storage or prune aggressively before retrying. On Linux hosts, verify the storage driver in docker info and look for overlay2-specific errors in daemon logs. If metadata corruption is suspected and cleanup does not help, restarting Docker daemon can clear stale file handles.

sudo systemctl restart docker

On Docker Desktop, a full engine restart from the UI often resolves stuck pulls caused by internal VM state.

Practical Verification Workflow

A reliable way to avoid regressions is to validate the solution in three passes: baseline, controlled change, and repeatability check. First, capture a baseline outcome before you apply fixes. This could be a failing command, a wrong output sample, a stack trace, or a screenshot of current behavior. Second, apply one focused change and rerun exactly the same checks so you can attribute improvements to a specific edit. Third, rerun the checks multiple times or with slightly different inputs to ensure the fix is not accidental or data-specific.

A lightweight template you can adapt for most projects looks like this:

1# 1) reproduce current behavior
2./run_example.sh > before.txt
3
4# 2) apply your change
5# edit config/code based on this article
6
7# 3) verify behavior after change
8./run_example.sh > after.txt
9diff -u before.txt after.txt

If your environment involves tests, add at least one focused regression test that would fail before the fix and pass after it. This turns a one-time troubleshooting success into a durable maintenance improvement, which is especially important when teams rotate ownership or upgrade dependencies later.

Common Pitfalls

• Re-running docker compose up repeatedly without clearing partial caches after pull failures.
• Ignoring disk inode limits even when raw disk space still looks available.
• Using floating tags like latest, which increases pull variability and cache churn.
• Running through unstable VPN or proxy settings without testing direct registry connectivity.
• Jumping straight to destructive cleanup (system prune -a) without checking whether the root issue is network or auth.

Summary

pulling fs layer ... closed indicates interrupted layer transfer or extraction. Fix it by checking daemon health, disk/inodes, and registry connectivity, then apply a staged cleanup and retry. For long-term stability, pin image versions, use a reliable network path or registry mirror, and keep Docker engine resources healthy.