Debug a Failing Deploy¶

When git push paas main fails or a release won't go healthy, work through these steps in order. For exhaustive coverage of build/runtime errors, see the Troubleshooting guide.

Step 1 — Watch live logs¶

paas logs --tail              # combined build + runtime
paas logs --deploy            # build phase only
paas logs --release v42       # logs of one specific release

The build output streams while git push runs, so you usually see the failure inline. Use paas logs to revisit it after the push exits.

Step 2 — Check release status¶

$ paas releases
ID    SHA       STATUS                 AT
v15   abc1234   release.timeout (5min) 3 min ago
v14   def5678   active                 1h ago

Statuses to watch: - building — Tekton build still running - release.timeout — release process didn't finish in 300s (configurable) - failed — build error or all replicas crashed - rolling — canary in progress - active — live and serving traffic

Step 3 — Inspect process state¶

$ paas ps
PROCESS  REPLICAS  READY  RESTARTS  STATUS
web      2         0/2    7         CrashLoopBackOff
worker   1         1/1    0         Running

Healthy: READY = REPLICAS and RESTARTS low.

Common build errors¶

"no buildpack matches"¶

remote: → ERROR: failed to detect: no buildpack groups passed detection

Paketo couldn't auto-detect your language. Force one in paas.toml:

[build]
buildpack = "paketo-buildpacks/python"

Or commit the language's marker file (package.json, requirements.txt, go.mod, etc.) to the repo root.

Port binding error¶

Symptom: Error: listen EADDRINUSE :::8080 or healthcheck times out at deploy.

Fix: Bind on process.env.PORT (or $PORT), never a hardcoded port. PaaS injects the port at runtime.

// ✅ correct
app.listen(process.env.PORT || 3000);
// ❌ broken on PaaS
app.listen(3000);

Build OOM¶

Symptom: Build container killed during npm ci or cargo build.

Fix: Increase build memory in paas.toml:

[build]
memory = "2Gi"

Common runtime errors¶

CrashLoopBackOff¶

$ paas logs --tail
panic: runtime error: invalid memory address or nil pointer dereference

Look at the first error in the logs (subsequent restarts can spam noise). Fix the bug, push again. Quick rollback while you investigate:

paas releases:rollback v14

Healthcheck timeout¶

remote: → Health: / not responding (waited 30s)
remote: ✗ Deploy failed

Your app started but / didn't return 200 in time. Either:

Add a fast /healthz route returning 200 < 1s, then point PaaS to it:

[deploy]
healthcheck_path = "/healthz"
healthcheck_timeout = 60

Speed up cold start (lazy-load heavy deps, defer DB connects past listen())

Migration timeout¶

The release process must finish in 300s by default. For long migrations:

[deploy]
release_timeout = 1200

Step 4 — Roll back¶

If a bad release is live and you can't fix forward fast enough:

$ paas releases:rollback v14
✓ Rolled back to v14 (def5678) in 18s

Rollback is instant — the previous image is still in Harbor and Deployment.spec.template is just updated.

Step 5 — Get help¶

paas events                # cluster events for the app (deploys, scales, OOMs)
paas debug:bundle          # zips logs + config + events for support

If the issue persists, file at forgejo.di2amp.com/octave/paas-runtime/issues with paas debug:bundle output.