Troubleshooting¶

Common installation issues¶

Symptom	Diagnosis	Fix
Fatal: `index.html not found under web`	Wrong cwd or missing assets	Run from `central/`, install `web/`, or set `CENTRAL_WEB_ROOT`
Build cannot find module `shared`	Missing sibling checkout	Keep `federation/shared` beside `federation/central`
Service exits immediately	Template parse failure, DB connect failure, invalid session TTL, thumbnails mkdir failure	Inspect `journalctl -u central -e`
Unit active but UI unstyled / missing shell	Shared UI root missing	Ensure `shared/ui` discoverable or set `FEDERATION_SHARED_UI_ROOT`

Configuration mistakes¶

Symptom	Likely mistake	Fix
Cards always empty with note about DB	Neither `CENTRAL_DATABASE_URL` nor `DATABASE_URL` set	Configure DSN in `/etc/central.env` and restart
Startup fatal mentioning session TTL	Bad `CENTRAL_SESSION_TTL` / `AUTH_SESSION_TTL`	Use Go durations (`24h`)
Links missing prefix under subpath	`BASE_PATH` / `X-Forwarded-Prefix` mismatch	Align route registration env and proxy header
Cookies not marked Secure on HTTPS site	Proxy omits `X-Forwarded-Proto: https`	Set/overwrite the header at the TLS edge
Discovery calls wrong host	Missing/incorrect `X-Forwarded-Host` or `ProxyPreserveHost`	Preserve Host; verify origin assembly
Catalog stale for ~45s	Expected cache behavior	Lower `CENTRAL_CATALOG_CACHE_TTL` in development

Authentication failures¶

Symptom	Cause	Fix
`401 authentication required` on admin APIs	Missing/expired cookie or PAT	Sign in again or supply valid `Authorization: Bearer`
`403 admin access required`	Authenticated non-admin	Add user to Administrators / set admin flags via an existing admin
`POST /login` returns `503`	Auth DB not configured	Set database URL
Invalid username/password HTML	Wrong credentials, disabled user, or username-not-email expectation	Confirm username login; check `enabled`
PAT works for `/api/me` but other services reject it	Downstream service may lack TokenStore	Use session cookie for those services until they support PATs
CLI `login` fails without cookie	Central did not set `acugis_session`	Verify Central auth DB and proxy path `/login`

Database errors¶

Symptom	Cause	Fix
Fatal connect/ensure schema	Bad DSN, unreachable Postgres, permission issue	Test DSN with `psql`; verify role privileges
Admin APIs `503 authentication database is not configured`	No DSN or non-Postgres store path	Configure Postgres URL
`500` with raw Postgres text on unique/FK failures	Expected classification for some errors	Correct payload (duplicate username/group name, missing FK ids)
Partial schema after failed boot	Non-transactional `EnsureSchema`	Resolve error and restart; inspect tables manually

Permission problems¶

Symptom	Cause	Fix
Card missing for anonymous users	Manual card not public, or resource lacks Public `view`	Set `is_public` or grant Public view on resource ACL
Imported card invisible to group	ACL grant missing / wrong service+resource_key pairing	Check `resources` and `resource_permissions`
Cannot delete Administrators/Public	Protected groups	Expected; create a different group instead
systemd cannot write thumbnails	Thumbnails outside `/opt/central` without matching write path	Keep dir under `/opt/central` or adjust unit `ReadWritePaths`

Deployment issues¶

Symptom	Cause	Fix
Apache 404 for `/api/catalog`	Enabled vhost missing catalog ProxyPass	Align with `../apache.conf/000-default-le-ssl.conf`
Service paths hit wrong backend	Proxy order / catch-all `/` too early	Keep service-specific ProxyPass before Central catch-all
Multiple Central instances missing images	Local thumbnail disk	Use shared storage or sticky single node
High discovery latency	Sequential service fetches + cold cache	Ensure downstream discovery healthy; tune TTL carefully

Logging locations¶

Source	Location
Central process	journald unit `central` (`journalctl -u central`)
Local foreground run	process stdout/stderr
Apache	`${APACHE_LOG_DIR}/error.log`, `access.log`

Useful debugging commands¶

# service status and logs
systemctl status central
journalctl -u central -f

# liveness
curl -sS http://127.0.0.1:8888/api/health

# anonymous vs authenticated identity
curl -sS http://127.0.0.1:8888/api/me
curl -sS -b /tmp/central.jar -c /tmp/central.jar \
  -X POST http://127.0.0.1:8888/login \
  -d 'username=admin&password=...&next=/'
curl -sS -b /tmp/central.jar http://127.0.0.1:8888/api/me

# catalog warnings
curl -sS -b /tmp/central.jar http://127.0.0.1:8888/api/catalog | jq '.warnings'

# confirm listening socket
ss -ltnp | grep 8888

# database smoke (operator workstation)
psql "$CENTRAL_DATABASE_URL" -c '\dt'
psql "$CENTRAL_DATABASE_URL" -c 'select count(*) from dashboard_users;'

When reporting issues, include the Central journal excerpt, /api/me authentication state, whether a DSN is configured, and any /api/catalog warnings.