Troubleshooting¶

Check the logs first:

docker logs -f justup

The container does not start¶

SECRET_KEY not set

justUp! does not start without SECRET_KEY. Generate a Fernet key:

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

See Environment variables.

Entrypoint aborts

The entrypoint exits if PUID/PGID are not numeric or are 0, if gosu is missing, or if /app/data is not writable by that user.

Wrong client IP in rate limits or audit log¶

The proxy IP appears instead of the client IP

Set UPMON_TRUSTED_PROXIES to the proxy address as the container sees it. See Reverse proxy.

Admin password unknown

docker exec -it justup justup-cli reset password admin

Account locked

Failed sign-ins lock out the IP and username with growing delay (up to one hour). Wait it out. See Authentication.

No notifications¶

Email does not arrive

Check the SMTP settings and send a test email. The delivery queue retries up to 5 times; Settings > Delivery Queue shows the log.

Signal does not send

Check that the signal-cli account is registered or linked and send a test message. See Notifications.

Everything shows `unknown`¶

The quality gate paused checks

Poor connectivity of the justUp! host pauses checks. Check the dashboard widget and the probe targets (Settings > Network). See Quality gate.

Ping or traceroute does not work¶

Missing capability

ping and mtr need cap_net_raw. Keep NET_RAW in the container's capabilities. See Docker.

Status does not update live¶

Live updates are delayed

The browser keeps one event stream (/ui/events) open. If a proxy buffers or cuts it, the page falls back to polling every 15 s. Disable response buffering for /ui/events; see Reverse proxy.

Server offline overlay or redirect to sign-in

The overlay appears when /health fails twice in a row and closes on its own. A redirect to sign-in means the session expired, was revoked, or the account was deactivated.

No geo data on the traceroute map¶

GeoLite2 database missing

Traceroute still works, but hops without another location source stay off the map. See Traceroute & maps.

A background service keeps crashing¶

Service is degraded

A watchdog restarts crashed background services and logs service=<name> event=<event> .... After repeated crashes a service is degraded and retried every 5 minutes.

docker logs justup 2>&1 | grep "event=crashed\|event=degraded"

GET /healthz lists the state of each service. Fix the cause named in the traceback; the service recovers on its next retry. Admins also get a Notification Center entry for a crash, for degraded, and for the recovery.