# Common Issues

> Diagnose deploy failures, missing logs, pending domains, and add-on connection errors.

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**:

```bash
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

```bash
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:

```bash
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

```bash
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:

```bash
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 and ready: `watasu addons --app my-app`
* Your app serves a Prometheus endpoint on `$METRICS_PORT` — the add-on injects this var (default `9464`); apps listening on a hardcoded port won't be scraped (see [Metrics](https://docs.watasu.io/observability/metrics.md))
* 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](https://docs.watasu.io/admin/billing-and-limits.md))

## 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](https://docs.watasu.io/workflows/review-apps.md))

## 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.

[View this page on the web](https://docs.watasu.io/troubleshooting/common-issues/)