Troubleshooting

Start with the symptom below. Run commands on the affected host and avoid posting tokens, enrollment codes, API keys, or the first-run password in an issue.

First checks

sudo serverbee status
sudo ss -ltnp | grep -E ':(80|443|9527)[[:space:]]'

Then inspect the logs for your deployment:

First-run password is missing

The random password is printed once, only when the first user is created. Read the complete last credentials block:

sudo journalctl -u serverbee-server --no-pager \
  | grep -A8 'FIRST-RUN ADMIN CREDENTIALS' | tail -n 9

docker logs serverbee-server 2>&1 \
  | grep -A8 'FIRST-RUN ADMIN CREDENTIALS' | tail -n 9

If a user already exists, restarting does not generate another password. Use the supported account recovery/admin path for that installation; do not delete the database to force first-run behavior.

Login loops or the cookie is not stored

Keep the public URL and cookie mode aligned:

• Plain http://IP:9527 requires auth.secure_cookie = false.
• HTTPS requires auth.secure_cookie = true, and the proxy must forward Host, X-Forwarded-Proto, and WebSocket upgrades.

After changing /opt/serverbee/etc/server.toml, run sudo serverbee restart server. Clear only the ServerBee site's cookies and retry. Do not disable Secure cookies on an HTTPS production deployment.

Port, DNS, or certificate setup fails

• Direct-IP mode needs inbound TCP 9527.
• Managed domain mode needs inbound TCP 80 and 443, and no non-Caddy listener on either port. Keep 9527 private.
• Confirm the domain resolves to this host with getent ahosts monitor.example.com.
• Inspect Caddy with sudo caddy validate --config /etc/caddy/Caddyfile and sudo journalctl -u caddy -n 100 --no-pager.

Fix DNS/firewall/listener conflicts first, then rerun sudo serverbee domain setup --domain monitor.example.com --email admin@example.com -y.

Agent stays offline or enrollment fails

1. Confirm the Agent's server_url exactly matches the browser's reachable HTTP/HTTPS origin.
2. Check the Agent log for expired, consumed, replaced, rate-limit, TLS, or connection errors.
3. Enrollment offers are bound, single-use, and expire after 10 minutes by default. Replace the exact outstanding offer on the existing Server when necessary.
4. Before claim, correct values locally:

sudo serverbee config set server_url https://monitor.example.com -y
sudo serverbee config set enrollment_code NEW_ONE_TIME_CODE -y

Do not rerun install agent over a managed Agent. After a successful claim, use graceful or emergency re-enrollment from the Server detail page instead of changing the consumed code.

The selected release channel is unexpected

sudo serverbee status
sudo serverbee upgrade --channel stable -y
sudo serverbee upgrade --channel beta -y

The default auto policy prefers a suffix-free stable release and falls back to a prerelease only when no stable release exists. The installer saves auto, stable, or beta per component and reuses it for upgrades; either explicit command above replaces the saved policy after a successful upgrade. Selection follows the SemVer suffix rather than GitHub's potentially incorrect prerelease flag. For deterministic recovery, pass --version vX.Y.Z and verify that exact release's assets/checksums. After an upgrade, confirm the service/container is healthy, its restart count is stable, /healthz succeeds, and the UI/About version matches the intended release.

Getting help

Include the deployment method, OS/init system, expected and actual version, redacted config keys, the exact command, exit status, and relevant log lines. State whether /healthz works and whether the failure affects Server, Agent, browser, or reverse proxy. Never include credentials or tokens.