Troubleshooting
Most pgpg problems come down to Docker, ports, or your license. This page lists the common ones and how to fix them.
Docker is not running
pgpg boots every sandbox as a Docker container, so the Docker daemon must be running before you start. If it is not, you will see something like:
Error: cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
Start Docker (Docker Desktop on macOS/Windows, or systemctl start docker on Linux) and try again. Confirm it is up with:
docker info
First start is slow
The very first start for a given PostgreSQL version pulls the image from the registry, which can take a while on a slow connection:
Sandbox booting...
Pulling postgres:16 (first run only)...
This is a one-time cost. Subsequent starts on the same version reuse the cached image and boot in seconds.
Port already in use
If another process is holding the port a sandbox wants, the boot fails:
Error: failed to bind sandbox port 55432: address already in use
Move or widen the range in your config (see Configuration):
[sandbox]
port_range = "60000-60100"
Then restart pgpg. The new sandbox picks the first free port in the range.
License or authentication error
If your license key is missing or invalid, pgpg refuses to start a scenario:
Error: license validation failed: no valid license key found
Sign in to refresh your credentials:
rillence login
Or check that license_key is set in ~/.config/rillence/config.toml (or RILLENCE_LICENSE_KEY in your environment).
Sandbox is in a weird state
If your investigation leaves the database confusing or wedged, restore the initial broken state without losing the scenario:
pgpg[stage-01/01-missing-index]> reset
Sandbox restored to initial state.
Sandbox won't tear down
If a sandbox seems stuck, stop removes its container:
pgpg[stage-01/01-missing-index]> stop
Sandbox stopped.
Orphaned containers
After a crash or a force-quit, a container may be left behind. pgpg cleans up stopped containers it owns on the next start, but you can also remove them by hand. pgpg-managed containers are labeled, so you can find and remove them:
docker ps -a --filter "label=rillence.pgpg"
docker rm -f $(docker ps -aq --filter "label=rillence.pgpg")
Low disk space
PostgreSQL images and sandbox volumes consume disk. If you have run many scenarios or pinned several versions, reclaim space with:
docker system df # see what is using space
docker image prune # remove unused images
docker volume prune # remove unused volumes
Removing an image just means the next start on that version pulls it again.