Troubleshooting Guide
Common container deployment failures, causes, and how to resolve them.
Symptom: Endpoint returns Gateway Timeout (504) or is unreachable.
Likely Cause: The container process binds to a port other than the port configured inside Kubeletto settings.
Solution: Ensure your web framework binds on 0.0.0.0:8080, or redeploy with the correct port flag: kubeletto deploy --app <name> --image <image> --port <port> --wait. You can also update the container port in the web console under Service → Settings.
Symptom: Build compiles successfully, but deployment status transitions to Failed.
Likely Cause: Missing runtime environment variables (e.g. database credentials) causing server initialization failure, or failure of readiness probe checks.
Solution: Stream output with kubeletto logs --follow or inspect details under the Logs tab inside the console. Ensure health endpoints (e.g. /healthz) return HTTP 200.
Symptom: Build fails during Nixpacks compilation or Dockerfile build.
Likely Cause: Syntax errors in your Dockerfile, missing dependency lockfiles, or compilation memory limits exceeded.
Solution: Check the detailed logs in the Build Logs console dashboard. Ensure your lockfiles (e.g. package-lock.json, go.sum) are present, and verify your local application builds successfully before pushing.