supabase start local stack Docker failure in CI

supabase start runs the whole Supabase stack (Postgres, PostgREST, auth, storage) as Docker containers. In CI it fails if the Docker daemon is not available, an image cannot be pulled, or a required host port is already in use.

What this error means

A "supabase start" step fails with "Cannot connect to the Docker daemon" or "port is already allocated", and the local database URL never becomes reachable.

failed to start docker container: Error response from daemon: Ports are not
available: exposing port TCP 0.0.0.0:54322 -> 0.0.0.0:0: address already in use

Common causes

No Docker daemon available

A runner without Docker, or where the daemon is not started, cannot launch the Supabase containers.

A required port is already bound

The default Supabase ports collide with another service in the job (a Postgres service container, a prior stack), so a container cannot bind.

How to fix it

Ensure Docker is running before start

1. Use a runner image with Docker, or start the daemon first.
2. Verify with docker info before running supabase start.
3. Stop the stack in a cleanup step so ports free up.

docker info >/dev/null
supabase start

Free the conflicting ports

Remove or reconfigure the service using the port, or stop a previously started stack before starting again.

supabase stop --no-backup || true
supabase start

How to prevent it

• Run supabase start only on runners with a working Docker daemon.
• Avoid binding the same ports with other service containers in the job.
• Always supabase stop in cleanup so ports are released.

Related guides