Common Issues

A symptom-first guide. Find what’s happening, jump to the section, run the diagnosis.

Deploy failures

Build fails immediately

Likely causes: Buildpack didn’t detect your app type, or your Dockerfile has an error.

Diagnose:

• Check the build output that streamed during git push watasu main.
• For buildpack failures: confirm your project has the standard markers for its language (package.json, Gemfile, requirements.txt, etc.) at the repo root.
• For Dockerfile failures: build it locally with docker build . to reproduce.

Build succeeds, release fails

Likely cause: Your release process (typically migrations) failed.

Diagnose:

• The release output is in the deploy stream and in the dashboard’s release view.
• Most often: a migration error or a missing config var the migration depends on.

Release succeeds, app crashes on start

Likely causes: missing config var, failed dependency, or your app didn’t bind to $PORT.

Diagnose:

watasu logs --app my-app
watasu config --app my-app   # confirm the var you expect is set

App is “running” but doesn’t respond

Returns 503 or connection refused

Likely cause: Your app is binding to 127.0.0.1 (localhost) instead of 0.0.0.0:$PORT.

Fix: Bind to 0.0.0.0:$PORT. Watasu sets PORT in the environment; your app must listen on it.

Process isn’t named web

Public HTTP routing only goes to processes named web or matching *-web. If your Procfile calls it server or app, it won’t be exposed.

Fix: Rename to web (or add a second *-web process if you need a non-default name) in your Procfile and redeploy.

Worker isn’t running

watasu pods --app my-app

Check:

• Does the Procfile define worker?
• Is worker scaled above zero?
• Does it crash on boot?

If the formation shows worker=0, scale it:

watasu pods:scale worker=1 --app my-app

If it’s scaled but logs show repeated crashes, fix the boot error and redeploy.

Domain stays pending

watasu domains:info www.example.com --app my-app

Check:

• The DNS record type matches what Watasu printed (typically CNAME).
• The DNS record points at the exact target Watasu printed — no typos.
• The domain is attached to the right process (use --process if you have multiple *-web).
• Your DNS provider’s TTL has had time to propagate.

Then:

watasu domains:wait www.example.com --app my-app

If it stays pending after a clean DNS change, your provider may be caching old records. Try dig against an external resolver to confirm the record is actually live.

Database or cache connection errors

Check, in this order:

1. Add-on is ready: watasu addons --app my-app — status should be ready.
2. Config vars exist: watasu config --app my-app — confirm DATABASE_URL (or REDIS_URL) is set.
3. App reads the right var name: especially with aliases. If the alias is REPORTING, your app should read REPORTING_DATABASE_URL, not DATABASE_URL.
4. App didn’t override the add-on var: if you config:set DATABASE_URL=... manually, you’ve broken the wiring. Unset it.

Metrics show empty graphs

• The metrics add-on is attached: watasu addons --app my-app
• Your app is actually exporting metrics on a Prometheus endpoint
• You’re looking at the right Grafana data source and the right time range
• Cardinality hasn’t blown the active-series limit (see Billing and Limits)

Traces are missing

• Your app is exporting traces (OpenTelemetry/OTLP)
• The tracing library is configured with the right endpoint
• The app is actually generating spans for the path you’re looking at
• The Grafana traces data source is connected

Review apps don’t appear

• The repo is connected to GitHub correctly
• The pull request matches the pipeline’s PR rules
• app.json exists in the PR’s source (it’s required — see Review Apps)

When to escalate

If you’ve checked the above and the symptom looks platform-side rather than app-side, collect:

• the app name
• the time the issue started (UTC)
• the exact CLI command or dashboard action
• relevant build, release, or log output

That’s the fastest path to a useful answer.