Troubleshooting¶

Common errors when deploying, building, or running apps on PaaS Runtime — with diagnostics and fixes.

Build fails: "no buildpack matches"¶

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

The Paketo buildpacks couldn't auto-detect your language. Diagnose:

Language	What buildpack expects
Node.js	`package.json` at repo root
Python	`requirements.txt`, `pyproject.toml`, or `setup.py`
Go	`go.mod` at repo root
Rust	`Cargo.toml` at repo root
Java	`pom.xml`, `build.gradle`, or `mvnw`
Ruby	`Gemfile` at repo root
PHP	`composer.json` at repo root
Elixir	`mix.exs` at repo root

Force a buildpack explicitly in paas.toml:

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

App crashes immediately after deploy¶

Symptom: paas ps shows the app in failed state, with restartCount increasing every 30s.

Diagnose:

paas logs --tail

Common causes:

Log signal	Fix
`EADDRINUSE: 0.0.0.0:8080`	Bind on `process.env.PORT`, not a hardcoded port
`Error: connect ECONNREFUSED 127.0.0.1:5432`	DB not provisioned or `DATABASE_URL` not bound — `paas addons`
`Cannot find module 'X'`	Missing dep in `package.json` — `npm i X --save`
`Out of memory`	Increase `[[processes]] memory = "512Mi"`
Healthcheck timeout	Add a fast `/healthz` route returning 200 < 1s

502 Bad Gateway¶

The app is running but nginx can't reach it. Check the readiness probe:

$ paas ps
PROCESS  REPLICAS  READY  STATUS
web      1         0      Healthcheck failing on /

Fix: ensure your app responds 200 on GET / (or override the healthcheck path):

# paas.toml
[deploy]
healthcheck_path = "/healthz"
healthcheck_timeout = 30

"Build cache poisoned" / stale dependencies¶

Force a fresh build (invalidates Paketo layer cache):

paas builds:retry --no-cache

Database migration timed out¶

Symptom: deploy stuck on release step for >5 min.

Migrations run as a Kubernetes Job with the app's runtime container. Long migrations:

$ paas releases
ID    SHA       STATUS                  AT
v15   abc1234   release.timeout (5min)  3 min ago

Fix: extend timeout in paas.toml:

[deploy]
release_timeout = 600   # seconds (default 300)

Or run the migration as a one-off outside the deploy:

paas run -- python manage.py migrate --no-input

OOMKilled¶

$ paas ps
NAME              STATUS       RESTART
web-abc-123       OOMKilled    5

The pod exceeded [[processes]] memory. Increase:

[[processes]]
name = "web"
memory = "512Mi"   # was "256Mi"

Or profile memory usage with paas debug:heapdump web (Node, JVM only).

Domain not resolving (custom domain)¶

$ paas domains
DOMAIN              STATUS
www.example.com    pending_dns

cert-manager waits for DNS verification. Add the TXT record shown by:

paas domains:verify www.example.com

Once DNS propagates (5-60 min), cert-manager issues a Let's Encrypt cert automatically.

Logs not appearing¶

If paas logs --tail shows nothing but the app is running, check:

App writes to stdout / stderr (not files). PaaS captures container logs.
Log level is high enough (LOG_LEVEL=info)
SigNoz is running (https://ma30.di2amp.com/runtime/signoz/ should return 200)

Get help¶

paas events                    # last 50 cluster events for the app
paas debug:bundle              # zips logs + config + events for support
paas describe                  # raw K8s describe (advanced)

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