Troubleshooting

Start with berth doctor. It checks each moving part and prints the command that fixes whatever's wrong.

A deploy failed. The error ends with the app's last log lines; for the whole story, berth logs myapp --build then berth logs myapp. The previous release is still serving. The usual suspects: the app listens on localhost instead of 0.0.0.0, or ignores $PORT; it's slow to boot (raise BERTH_HEALTH_TIMEOUT); or / returns a 5xx (point BERTH_HEALTHCHECK at a health endpoint).

A push didn't deploy. Run berth events. You'll see webhook entries if GitHub reached the Mac, or webhook.rejected for a bad signature. Without webhooks, polling picks the push up within a minute. A monorepo app ignores pushes that don't touch its path.

berth: berthd is not running. Start it with launchctl kickstart -k gui/$UID/dev.berth.berthd. Its log is ~/.berth/logs/berthd.log.

The public URL doesn't work but the .local one does. That's the tunnel. berth doctor checks it's connected and that the wildcard DNS record resolves. cloudflared's log is ~/.berth/logs/cloudflared.log.

An app says crashed. It failed to start 10 times in a row. Look at berth logs myapp, fix it, then berth restart myapp or push.

berth upgrade says it's done but the version didn't change. You're on 0.1.0 or 0.1.1: run brew update && brew upgrade berth once.

I edited files in ~/.berth by hand. Run berth reload and berthd rebuilds the proxy and tunnel config and the set of running containers from the files.

Environment variables