Try or ByeTry or Bye

Supabase Start Not Working (Docker Container Unhealthy)

Workaround available macOS, Windows, Linux (CLI) Updated October 21, 2026

Quick answer

Local 'supabase start' failures are usually leftover containers, port conflicts or an unsupported Docker runtime. Stop everything, remove stale containers and retry with --debug.

Most likely fix: Stop and clean up.

Symptoms

supabase start hangs or fails with 'container is not ready: unhealthy', name conflicts, or the Postgres container restarting after a CLI upgrade.

Why it happens

  • Stale containers from a previous run
  • Ports 54321-54324 already in use
  • Rancher Desktop / Podman health-check incompatibilities
  • Linux Docker permissions
  • Postgres image upgrade incompatible with existing local volume

How to fix it

Try these in order — the most common fix is first.

  1. 1. Stop and clean up

    1. Run supabase stop --no-backup
    2. Run docker ps -a and remove leftover supabase_* containers

  2. 2. Debug the unhealthy container

    1. Run supabase start --debug
    2. Run docker logs <container_name> for the failing service

  3. 3. Free the ports

    1. Check another project or app isn't using ports 54321-54324
    2. Change ports in supabase/config.toml if needed

  4. 4. Use Docker Desktop or update the CLI

    1. Switch from Rancher Desktop to Docker Desktop if vector is unhealthy
    2. Update the CLI for the Podman health-check fix, or use --ignore-health-check

  5. 5. Fix Linux permissions

    1. Add your user to the docker group instead of running with sudo

This guide also covers

  • supabase start not working
  • supabase container is not ready unhealthy
  • supabase local docker error
  • supabase cli start failed

Still not working?

If Supabase keeps failing, you're not alone. See every Supabase problem users report or the alternatives people switch to.

Other Supabase errors