Skip to content
Gantry docs home
Gantry on GitHub,

Troubleshooting

Fixes for the problems people hit most: busy ports, permission errors on Linux, stale layers and slow first builds.

GuidesUpdated 1 Oct 20265 min read

Run gantry doctor first

Most problems show up in gantry doctor. It checks the install, kernel features, the VM, ports and the layer cache in about two seconds, and prints a fix next to anything that isn't ok.

$ gantry doctor  ok    gantry 2.8.1 (darwin-arm64)  ok    vm running · 4 CPUs · 6 GB memory  ok    layer cache · 3.1 GB · 214 layers  warn  port 5432 is taken by pid 812 (postgres)  ok    registry.example.com · logged in as ana

Port already in use

error[E0412]: can't publish db on :5432, the port is taken by pid 812 (postgres)

Something else already has the port, often a database installed with your system's package manager. Stop it, or publish on a different host port for this run:

$ gantry up --port db=5433:5432

To make that permanent, change ports in gantry.toml. Other services still reach the database at db:5432 on the project network, so only tools on your machine need the new port.

Permission denied on Linux

error[E0107]: newuidmap: write to uid_map failed: Operation not permitted

Your user has no subordinate ID range, which rootless containers need. Add one, then log out and back in:

$ sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 $USER
Don't reach for sudo gantry
Files created in the layer cache would then belong to root, and every later run as your own user fails with a different permission error.

Builds ignore lockfile changes

Gantry keys the dependency layer on the lockfile's contents. If you edited package.json without running an install, the lockfile didn't change and neither does the build. Run your package manager's install, then build again.

If a layer really is stale, rebuild just that layer and keep the rest of the cache:

$ gantry build web --no-cache=deps

Slow first build on macOS

The first build pulls base images and fills the cache; two to four minutes is normal on a fresh machine. If later builds are slow too, the VM is probably short on memory:

$ gantry vm set --memory 6GB --cpus 4

Projects with many small files, like a large node_modules, build faster with sync = "fast" in the build settings.

Getting help

Ask in GitHub Discussions and attach the output of gantry doctor --report, which leaves out tokens and hostnames. For bugs, open an issue with the command you ran and its full output. Maintainers triage every weekday, and most issues get a first reply within a day.