Troubleshooting

Common problems + solutions, sorted by symptom.

Container

Container does not start / exit code 1 immediately on start

Check logs:

docker logs itsweber-mesh --tail 50

Most common causes:

• MESH_SESSION_SECRET not set or too short — variable missing from env vars or less than 32 characters. Generate with openssl rand -hex 32 and pass via -e MESH_SESSION_SECRET=....
• OAuth2 mode but issuerUrl/clientId missing — you set auth mode to oauth2 but did not fill in all required fields. Bootstrap hard block. Fix: set auth.mode: "open" in /data/config.json (or temporarily replace the container with the backup).
• Permission denied: /data/config.json — volume mount permissions wrong. On the host: chown -R root:root /path/to/data (Mesh runs as root in the container because the Unraid socket mount would fail otherwise).

WebUI loads but page is white

• Browser cache is the most common cause. Ctrl + F5 (hard refresh).
• Open console errors in browser devtools — if Hydration mismatch: usually a custom CSS error. Set theme.customCss: "" in config.json and reload.

Schema migration does not complete

• Logs show Config migrated and persisted with from/to versions
• If failed: a backup is created at /data/config.json.pre-vN → cp /data/config.json.pre-vN /data/config.json, then restart the container and report with a log excerpt in the issue tracker

Healthchecks / Status display

Service shows "offline" even though it is running

• HTTP pings only accept 200/204/301/302/401. If your service returns 403 (auth wall) or 503 (loading), the check fails. Change the service entry → ping type to "No ping" or extend the allow list in config.json.
• TCP pings need a reachable port — if the host does not respond at all (e.g. container down), this takes until timeout (default 3 s).
• Container DNS: Mesh runs in a bridge network. *.local (mDNS) is not resolved in many setups. Fix: use an IP instead of hostname, or add your own DNS (Pi-hole/AdGuard) as dns: in docker-compose.

Status dots in the header are grey

• React Query only refreshes after staleTime — wait up to 10 s on the first load
• F5 forces a refresh
• Check logs: docker logs itsweber-mesh | grep healthcheck — missing pings appear with pingTarget kind: ...

Auth & Login

SSO / OAuth2 — "Redirect URI Error"

Authentik/Keycloak shows this error when the app sends a redirect_uri that is not registered in the IdP.

Cause 1 — URI not registered: Add the redirect URI https://<mesh-domain>/api/auth/oidc/callback in the IdP.

Cause 2 — Reverse proxy missing headers: Mesh builds the callback URL from X-Forwarded-Proto + Host. Without these headers http://0.0.0.0:3000/api/auth/oidc/callback is produced — which is never registered in the IdP. Make sure the proxy sends:

proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Host $http_host;

NPM, Traefik and Caddy do this automatically.

SSO — "Code exchange invalid" on /api/auth/oidc/callback

Same cause as above: the IdP rejects the token request because the redirect_uri in the token exchange does not match the one used during authorisation. Check proxy headers.

In the container log:

"error": "invalid_client", "error_description": "Client authentication failed"

Also check: is the client secret saved in Mesh? Admin → Auth → OIDC form → client secret field must not be empty (required for confidential clients).

SSO — Redirect to 0.0.0.0:3000 after login

Same proxy header cause, this time on the post-login redirect. After fixing the headers, clear the browser cache and try again.

Admin area accessible despite missing login

If the auth mode changes (e.g. from open to oauth2), an old mesh_session cookie remains valid for 24 h. The user is still authenticated — this is not a bug. To immediately invalidate all active sessions: rotate MESH_SESSION_SECRET in the container and restart.

Integrations

Home Assistant — "Token invalid"

• Long-Lived Access Tokens do not expire, but are invalidated when the user in HA is deleted or password-reset
• Test directly: curl -H "Authorization: Bearer <token>" https://home.example.com/api/ → expected {"message": "API running."}

AdGuard — statistics show 0

AdGuard's /control/stats returns the last 24 h as an array, not as an aggregate. We read the fields num_dns_queries + num_blocked_filtering (singular aggregates), which are missing in some older AdGuard versions. Update to AdGuard 0.107+ to fix.

UniFi — "Auth failed"

• API key mode is required from UniFi 8.x. Generate an API key in the UniFi account (not in the controller!).
• For self-signed certificates: enable verifyTls: false in the integration

Glances — see Glances wiki

Frigate — events missing

Frigate auth: if Frigate is behind a reverse proxy with Basic Auth, add the auth header in the Mesh integration. Otherwise: verifyTls: false if self-signed.

ESPHome — no sensors visible

• Required: web_server: component in the ESPHome YAML
• Test: curl http://<esphome-ip>/sensor/list → JSON with sensor IDs
• v3 devices stream via SSE on /events. If nothing arrives: check ESPHome version, set web_server.version: 3 in YAML

Zigbee2MQTT — devices not recognised (auto mode)

Auto-discovery reads from Home Assistant via template API: device_attr(<device_id>, 'identifiers'). Prerequisites:

1. Z2M connected to Home Assistant via MQTT (standard setup)
2. HA has MQTT discovery enabled
3. Mesh has a working HA integration

If this does not match: switch mode to ha (legacy) and create an HA group with the Z2M devices, or switch to mqtt (v1.7+).

Theme & UI

Dashboard looks "broken" after Custom CSS edit

• Custom CSS has a syntax error. Browser devtools → Console → find CSS parse errors
• Quick fix: empty the field theme.customCss: "" in /data/config.json, reload Mesh

Theme does not switch

• React Query cache: up to 60 seconds, or F5
• If data-theme on <html> is not updated: check whether the ThemeSync component is running (should be included on every page)

Mobile

Horizontal scroll on smartphone

The app-header shrinks below 820 px to 3 columns + hamburger menu button. If there is a bug, open an issue with a screenshot + browser/user-agent.

Widgets look wrong on mobile

Some widgets have a minimum width. Below w<minWidth they switch to compact mode (small tile). If this mode kicks in too early, drag w larger in edit mode or check wideThreshold in the service/widget editor.

Performance

Dashboard is slow to load

• With >50 services configured: the healthcheck scheduler limits with p-limit(8) in parallel, but does a full sweep every 10 s. With many TCP targets (>30) the healthcheck interval may be configurable in a future version
• Container memory: for >100 services consider setting -e NODE_OPTIONS="--max-old-space-size=512"

Image is large

Standard ~150 MB (Alpine + Next.js Standalone). A :latest-slim (without lm-sensors / GPU tools) is conceivable — may come in v1.6.

If nothing helps

1. Collect logs: docker logs itsweber-mesh --tail 200 > mesh.log
2. Screenshot of browser console errors
3. Open an issue on GitHub — please without real API keys/tokens