Docker Troubleshooting

Docker issues are the most common blocker for local development. This guide covers how to properly start, stop, and recover from broken Docker states.

Starting Your Project (The Right Way)

Follow this sequence every time you start development:

Step 1: Ensure Docker Desktop is Running

Before running any commands, Docker Desktop must be fully started:

1. Open Docker Desktop
2. Wait for the whale icon in the system tray to stop animating
3. Wait until the dashboard shows "Docker Desktop is running"

Verify Docker is ready:

docker ps

If this returns an error, Docker isn't ready yet. Wait and try again.

Step 2: Check for Orphaned Containers

Sometimes containers from previous sessions are stuck:

docker ps -a

If you see any supabase_* containers, clean them up first:

pnpm supabase:web:stop

Step 3: Start Supabase

pnpm supabase:web:start

Wait for it to complete. You should see the API URL, keys, and Studio URL printed.

Step 4: Start the Development Server

pnpm dev

Common Issues and Fixes

"Cannot connect to the Docker daemon"

Cause: Docker Desktop isn't running or hasn't fully initialized.

Fix:

1. Open Docker Desktop
2. Wait 30-60 seconds for full initialization
3. Run docker ps to verify it's ready

"Port 54321 is already in use" (or 54322, 54323, 54324)

Cause: Previous Supabase containers didn't shut down properly.

Fix (Windows):

# Find what's using the port
netstat -ano | findstr :54321

# Kill the process (replace <PID> with the actual number)
taskkill /PID <PID> /F

Fix (Mac/Linux):

lsof -i :54321
kill -9 <PID>

Alternative - Nuclear option:

# Stop everything Supabase-related
pnpm supabase:web:stop

# Kill ALL running containers
docker kill $(docker ps -q)

# Start fresh
pnpm supabase:web:start

"Container supabase_db_* is unhealthy"

Cause: Database container failed to start properly, often due to corrupted volumes.

Fix:

# Stop Supabase
pnpm supabase:web:stop

# Remove the database volume (THIS WIPES LOCAL DATA)
docker volume rm supabase_db_next-supabase-saas-kit-turbo

# Start fresh
pnpm supabase:web:start

"Error response from daemon: conflict"

Cause: Container names conflict with existing containers.

Fix:

# Stop all Supabase containers
pnpm supabase:web:stop

# Remove ALL stopped containers
docker container prune -f

# Start fresh
pnpm supabase:web:start

Supabase Starts But Migrations Fail

Cause: Database state doesn't match migration history.

Fix:

# Complete reset - wipes everything and reapplies all migrations
pnpm supabase:web:reset

"image not found" or "manifest unknown"

Cause: Docker images are corrupted or outdated.

Fix:

# Stop Supabase
pnpm supabase:web:stop

# Remove all Supabase-related images
docker images | grep supabase | awk '{print $3}' | xargs docker rmi -f

# Start fresh (will re-download images)
pnpm supabase:web:start

Windows PowerShell alternative:

docker images | Select-String "supabase" | ForEach-Object { docker rmi -f ($_ -split '\s+')[2] }

Everything is Broken (Full Reset)

When nothing else works, do a complete Docker cleanup:

# 1. Stop Supabase
pnpm supabase:web:stop

# 2. Stop all running containers
docker kill $(docker ps -q) 2>/dev/null

# 3. Remove all stopped containers
docker container prune -f

# 4. Remove Supabase volumes (WIPES ALL LOCAL DATA)
docker volume rm supabase_db_next-supabase-saas-kit-turbo
docker volume rm supabase_storage_next-supabase-saas-kit-turbo
docker volume rm supabase_config_next-supabase-saas-kit-turbo

# 5. Remove unused images (saves disk space)
docker image prune -f

# 6. Start fresh
pnpm supabase:web:start

Windows users: If the $(docker ps -q) syntax doesn't work, run commands separately:

docker ps -q | ForEach-Object { docker kill $_ }
docker container prune -f

Preventing Issues

Always Stop Properly

Before closing your computer or switching projects:

pnpm supabase:web:stop

This gracefully shuts down all containers and prevents orphaned processes.

Don't Force-Quit Docker Desktop

Closing Docker Desktop without stopping containers first can cause:

• Orphaned processes holding ports
• Corrupted database volumes
• Container name conflicts

Proper shutdown sequence:

1. Run pnpm supabase:web:stop
2. Wait for completion
3. Then quit Docker Desktop (if needed)

Keep Docker Desktop Updated

Outdated Docker versions can cause compatibility issues. Check for updates in Docker Desktop settings.

Quick Reference Commands

Verifying Everything Works

After starting Supabase, verify all services are running:

If all four check out, you're ready to run pnpm dev.