Docker Compose — Port & Volume Issues

1 minute read

Port conflicts and volume problems are among the most common Compose issues.

Port Already in Use

Error: Ports are not available: listen tcp 0.0.0.0:3000: bind: address already in use

Find What’s Using the Port

# macOS / Linux
lsof -i :3000

# Alternative
ss -tlnp | grep 3000

Fix Options

  1. Stop the other process:
kill $(lsof -t -i :3000)
  1. Use a different host port:
ports:
  - "3001:3000"     # Map to 3001 instead
  1. Use dynamic ports:
ports:
  - "3000"          # Docker assigns a random host port

Volume Mount Not Working

Path Doesn’t Exist

Error: failed to mount: no such file or directory

Fix: Create the directory first:

mkdir -p ./data

Permission Denied in Container

docker compose exec api ls -la /app/data
# drwxr-xr-x root root   ← owned by root

Fix: Match UID/GID:

services:
  api:
    image: myapi:latest
    user: "1000:1000"
    volumes:
      - ./data:/app/data

Or fix permissions:

sudo chown -R 1000:1000 ./data

Named Volume Not Persisting

services:
  db:
    image: postgres:16
    volumes:
      - db-data:/var/lib/postgresql/data

volumes:
  db-data:              # ← Don't forget this!

If you omit the top-level volumes: declaration, Compose treats it as a bind mount to a path named db-data.

Volume Data After Rebuild

Named volumes persist across docker compose down:

docker compose down        # Data preserved ✓
docker compose down -v     # Data DELETED! ✗

Stale Volumes

# List volumes
docker volume ls

# Remove unused volumes
docker volume prune

# Remove specific volume
docker volume rm myapp_db-data

Summary

Issue Diagnosis Fix
Port in use lsof -i :PORT Change port or kill process
Path not found Check host path exists mkdir -p ./path
Permission denied Check file ownership chown or user: in compose
Volume not declared Missing top-level key Add volumes: section
Data lost Used down -v Avoid -v for important data

Quick Reference

Item Detail
Port in use lsof -i :PORT to find process
Permission denied Match UID/GID with user: key
Volume not declared Add to top-level volumes: key
Data deleted docker compose down -v removes volumes
Prune docker volume prune for cleanup

You may also enjoy