Skip to content

Troubleshooting

Jump to bottom
itsDNNS edited this page Apr 30, 2026 · 1 revision

Troubleshooting

Use this page as the first stop when Tribu does not behave as expected.

Before asking for help

Collect these details and redact private values:

  • install method: Docker Compose, Portainer, Dockge, Dockhand, or other
  • Tribu version or release tag
  • reverse proxy: Caddy, Nginx, Traefik, or none
  • whether frontend, backend, PostgreSQL, and Valkey containers are running
  • browser and device for UI problems
  • logs with secrets removed

Never share tokens, passwords, private URLs, real family data, webhook IDs, VAPID keys, JWT secrets, database URLs, or screenshots containing credentials.

First checks

docker compose ps
docker compose logs backend
docker compose logs frontend
docker compose logs postgres

Expected baseline:

  • backend is running on port 8000 inside the stack
  • frontend is running on port 3000 inside the stack
  • PostgreSQL is internal only
  • Valkey is internal only
  • reverse proxy routes public traffic to the correct services

Install and container startup

Backend exits immediately

Common causes:

  • missing JWT_SECRET
  • missing POSTGRES_PASSWORD
  • invalid DATABASE_URL
  • PostgreSQL not ready during first initialization

Try:

docker compose logs backend
docker compose restart backend

Frontend opens but API calls fail

  • Confirm /api/* reaches the backend.
  • If proxying through the frontend, confirm the frontend can reach the backend.
  • Check browser DevTools network errors.

Login and cookies

If login succeeds but you return to the login page:

  1. If using HTTPS, set SECURE_COOKIES=true.
  2. Confirm your proxy forwards X-Forwarded-Proto.
  3. Confirm the browser receives the cookie with the expected flags.
  4. For local HTTP testing, keep SECURE_COOKIES=false.

Reverse proxy paths

These paths matter:

Path Target
/api/* backend, usually with /api stripped if proxying directly
/ws/* backend with WebSocket upgrade headers
/dav and /dav/* backend
/.well-known/caldav backend
/.well-known/carddav backend
/auth/oidc/* frontend, which rewrites to backend
everything else frontend

Phone sync

If DAV sync fails:

  • use the URL from Settings > Phone sync
  • use your Tribu email as username
  • use a Personal Access Token as password
  • confirm token scopes
  • verify /dav and well-known DAV paths in the reverse proxy

Push notifications

If browser push fails:

  • set all three VAPID variables
  • restart the backend
  • use HTTPS
  • check browser notification permissions
  • run push diagnostics in Settings
  • on iOS, use the installed Home Screen app on supported versions

Shared Home Display

If display mode fails:

  • create a new pairing link from an admin account
  • open the pairing link on the display device once
  • confirm the token is removed from the URL after first load
  • do not expect a normal user session to authenticate /display
  • if revoked, re-pair the display

Home Assistant and webhooks

If Home Assistant cannot reach Tribu:

  • confirm the Home Assistant container/host can resolve and reach the Tribu URL
  • use !secret values instead of raw tokens in YAML
  • check Home Assistant automation traces
  • use Tribu's webhook test button before adding real automations

Backups and restores

If backup creation fails:

  • check backend logs
  • confirm the /backups mount is writable by the backend container
  • check disk space

If restore fails:

  • confirm the archive is a Tribu backup archive
  • use a fresh stack when testing restore drills
  • keep .env, Compose overrides, reverse proxy config, and TLS material in your normal server backup

Where to ask

Clone this wiki locally