Troubleshooting

Start by checking that the server is up, and reading its logs:

docker compose ps
docker compose logs --tail 100 server
curl http://localhost:3000/health

The server won’t start

Set AUTH_SECRET in .env: Compose needs AUTH_SECRET. Make one with openssl rand -base64 32, and put it in .env next to compose.yaml.

It can’t connect to the database after changing POSTGRES_PASSWORD: Postgres keeps the password from its first start. Put the old one back in .env.

The wizard asks for a code I can’t find

It’s in the logs, from docker compose logs server. A new one is made at each start, so use the most recent.

If ADMIN_EMAILS is set, no code is asked for, and the first account must use one of those addresses.

A watch or phone can’t connect

• Is it HTTPS with a valid certificate? Watches need this. Open /v1/meta on your address in a browser, and check there’s no certificate warning.
• Is PUBLIC_URL right? It has to be the https:// address people use. Settings → Server → HTTPS says when it’s set up correctly.
• Can it be reached from outside your network? A Garmin watch’s direct sync goes through Garmin Connect, and needs this.
• Did the address change? Phones and watches linked to the old address need signing in or linking again.

The Garmin watch shows request failures as codes:

Code	Meaning
-1001	The address isn’t HTTPS
-400	An answer the watch couldn’t read
-104	No connection to the phone
401	The watch is no longer linked
404	A route the server doesn’t have, so the server may be out of date

Notifications don’t arrive

• Is it turned on? Each person turns on Tell me about weather risks in the app’s Settings, under Match reminders, and the phone has to allow the app’s notifications. It’s on Android for now.
• Doesn’t the setting show? The app has to be a build with Firebase settings, and the server has to offer notifications, so check push is in capabilities from /v1/meta and that PUSH_RELAY_URL isn’t off.
• Is there a match to warn about? It only covers scheduled matches with a venue on the map, kicking off in the next 3 days, when weather is on. Each risk notifies once, plus once more if it becomes likely.
• Is the server at a limit? Look for Over the push relay's in docker compose logs server. See the limits.
• Can the server reach the relay? Look for The push relay can't be reached in the logs, and check it can make outgoing HTTPS requests.

People are locked out for too many tries

Behind a second proxy such as Cloudflare, everyone can look like one visitor, so they share one limit on wrong passwords. Set TRUSTED_IP_HEADER to the header that proxy uses. For Cloudflare, it’s CF-Connecting-IP.

A webhook won’t save

Addresses that are, or look up to, private, loopback or link-local are refused, so nobody can use a webhook to reach into the server’s network. For receivers on your own network, set WEBHOOK_ALLOW_PRIVATE=true.

Saved email or weather settings disappeared

They’re encrypted with a key made from AUTH_SECRET, so they count as unset after that changes. Enter them again under Settings → Server.

A restore fails

Check for free space in the container, up to the 2 GB a restore can take. Check your proxy’s upload limit too: nginx needs client_max_body_size, and Cloudflare’s free plan stops at 100 MB.