ื“ืœื’ ืœืชื•ื›ืŸ ื”ืจืืฉื™

Docker Troubleshooting

Resolve common Docker-related issues.

Container Won't Startโ€‹

Symptom: Container exits immediately

Fix: Check logs:

docker logs gauzy-api --tail 100

Common causes:

  • Missing required environment variables
  • Database not ready yet (use depends_on and health checks)
  • Port conflict

Database Not Readyโ€‹

Symptom: ECONNREFUSED in API container

Fix: Use health check in docker-compose.yml:

db:
  image: postgres:16
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U postgres"]
    interval: 5s
    timeout: 5s
    retries: 10

api:
  depends_on:
    db:
      condition: service_healthy

Permission Deniedโ€‹

Symptom: EACCES: permission denied

Fix: Check file permissions in volumes:

sudo chown -R 1000:1000 ./data

Image Pull 401โ€‹

Symptom: unauthorized: authentication required

Fix: Login to GHCR:

echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin

Out of Disk Spaceโ€‹

Symptom: no space left on device

Fix:

docker system prune -af
docker volume prune -f

Slow Buildโ€‹

Fix: Use multi-stage builds and .dockerignore:

node_modules
.git
*.md
dist