# Troubleshooting

## Server does not start

Symptoms:

- immediate process exit
- `JWT_SECRET is not set`
- DB connection errors

Checks:

- verify `.env` exists and has required values
- ensure `JWT_SECRET` has 32+ chars
- confirm Postgres is up: `docker compose ps`

## `401 Authentication required` on `/get-session`

Expected when no cookie/session exists.

If unexpected:

- verify browser sends cookies
- verify `credentials: include` in client fetch config
- confirm same-origin/proxy path is used

## CORS failures from browser

Symptoms:

- preflight blocked
- missing `Access-Control-Allow-Origin`

Fix:

- add app origin to `TRUSTED_ORIGINS`
- restart server after env changes

## `500 Internal server error` during login or callback

Symptoms:

- browser only shows `500 Internal server error`
- login from one app domain to a sibling auth domain fails without a useful reason

Checks:

- copy the response `traceId` or `x-athena-trace-id`
- inspect the server log entry `auth request failed`
- compare `host`, `forwarded_host`, `origin`, `referer_origin`, `base_url`, `public_base_path`, `cookie_domain`, and `trusted_origins_count`
- confirm the deployed app origin is trusted and the auth `BASE_URL` matches the public auth host
- confirm shared-session setups also set `ATHENA_AUTH_COOKIE_DOMAIN` for the parent domain; `TRUSTED_ORIGINS` alone is not enough

## Verify-email not applying

Symptoms:

- clicking email link opens app page but user stays unverified

Checks:

1. verify link must hit `/api/auth/verify-email?token=...`
2. if callback is used, it must be in `callbackURL` query value, not replacing verify endpoint
3. confirm token exists and not expired in DB
4. check response headers and status

## Slow responses

Use response headers:

- `X-Athena-Time` for backend processing time
- if proxied through Next demo also compare `X-Athena-Proxy-Time`

If proxy time is much larger than backend:

- debug Next proxy route / local network / browser overhead

If backend time is high:

- inspect DB latency
- inspect SMTP or external provider calls
- profile specific endpoint

## Wrong auth base path

Symptoms:

- `404` on `/api/auth/*`

Fix:

- align `AUTH_BASE_PATH` (server) with client base path
- for Next demo, keep `NEXT_PUBLIC_AUTH_BASE_PATH=/api/auth`
- restart both server and Next app after config change
