Troubleshooting

Start with the build ID, current status, API startup/runtime logs, and administrative build logs. Public progress intentionally omits detailed compiler errors.

Symptom	What to check
Server exits during startup	PostgreSQL DSN/connectivity, migration privileges, Docker endpoint, selected artifact backend and bucket access
Browser has no engine versions	A fresh catalog is empty; register an engine through administration
Module absent from picker	Module has a release, minimum engine version is eligible, and the selected major/minor compatibility list includes it
Session does not work on local HTTP	Legacy development needs GBB_COOKIE_SECURE=false; public human sessions require HTTPS
Token fails on a public instance	Anonymous/Authelia mode retires legacy token workflows; use the browser and configured admin login
ImagePullBackOff	Application registry credentials and image tag/digest; toolchain access inside dind is a separate check
Compiler image cannot be found	Image prefix matches build tags and image exists in the compiler daemon's store; rootless Podman commonly needs localhost/gbb/
Workspace missing in compiler container	Use bind mode and matching absolute paths on API and daemon; named volume mode does not copy the prepared tree
Workspace permission denied under Podman	Rootless UID mapping; local configuration commonly needs container_user: "0:0"
Clone fails for a private module	SSH key permissions, known-host database, endpoint, ref, and preparation process network access
Container exits with 137 / OOMKilled	Distinguish API Git-clone memory from compiler-link memory; inspect the container's actual limit and reduce parallelism
409 when submitting	Refresh stale catalog selections; check whether an idempotency key was reused with different contents
429	Honor Retry-After; inspect quotas, request or stream limits, and transfer concurrency
503 in public mode	Check PostgreSQL/Redis/bucket health, ban-index readiness, queue capacity, and gateway route cutover
Progress is sparse	Public logs are sanitized categories; ask an administrator to inspect raw logs
SSE arrives in one burst	Inspect proxy buffering and timeouts; public reconnects should preserve Last-Event-ID
Download stopped after IP change	Reverify in the same browser; sessions are bound to browser and canonical IP
Artifact unavailable	Build succeeded, artifact name is listed, retention has not expired it, publication metadata and stored object agree
Gateway readiness fails on new database	Gateway does not migrate; initialize schema through the API first
Windows ARM64 request rejected	The shipped Windows compiler only supports x86_64
macOS image skipped	Supply the required Apple SDK using the documented build process

Useful diagnostics

curl --fail-with-body http://localhost:8080/livez
curl --fail-with-body http://localhost:8080/readyz
./bin/gbb status --json BUILD_ID
./bin/gbb build --godot 4.4-stable --platform linuxbsd --dry-run

The CLI status command needs a legacy token-authenticated server. For a Kubernetes deployment, inspect pod events and logs in the namespace used by your overlay. Check both the API and Docker sidecar; a healthy API process does not prove a compiler image can run.

When reporting a bug, include the revision, deployment mode, target/architecture, build ID, relevant sanitized diagnostics, and reproduction steps. Exclude credentials, private repository URLs, raw cookie values, and secret-bearing log output.