Troubleshooting

Installation & first run

"The setup wizard is asking for a token"

That's the first-run setup token. On the server:

docker compose logs api | grep -A1 "SETUP TOKEN"

Lost it / logs rotated? Restart the API — the token re-prints on every startup until setup completes:

docker compose restart api && docker compose logs api | grep -A1 "SETUP TOKEN"

Getting 429 Too many attempts on the token screen means repeated wrong guesses — wait a minute and paste it carefully (it's case-sensitive).

The site won't load at all

docker compose ps          # is anything restarting/exited?
docker compose logs api    # startup errors usually land here

Port 80 already in use → another web server owns it. Stop it, or remap NexaDesk's nginx port in docker-compose.yml.
api restarting in a loop → almost always .env (missing/invalid required variables) or the database failing to start. docker compose logs db for the latter.

"Password must be at least 8 characters" and other wizard errors

The wizard validates as you go — mismatched passwords, invalid emails, and short passwords are rejected with a message. Fix and resubmit; nothing is saved until each step succeeds.

A staff member can't get past 2FA

Codes are time-based — check the device clock on the phone with the authenticator app.
Repeated failures trip rate limiting — wait 60 seconds.
Authenticator lost? An admin can manage the account under Settings → Users.

Login is rate-limited per IP. Wait a minute. If it persists for many users at once behind one NAT/proxy, make sure your reverse proxy forwards real client IPs.

Forgot-password emails never arrive

The reset flow emails through your connected channel — if no email channel is connected and working, the mail can't go out. Check Settings → Channels and the worker logs.

Email channels

Emails aren't becoming tickets

Settings → Channels — is the channel connected and enabled?
Check ingestion logs: docker compose logs worker
IMAP: right folder? Right poll interval? Credentials still valid?
M365: OAuth consent can expire or be revoked — reconnect the mailbox.

Replies from technicians aren't reaching requesters

Check the SMTP (or M365) sending side on the channel card, and look for send errors in docker compose logs worker.

Licensing & NetManager

Your license must include the netmanager feature — check Settings → License
Only staff (admin/technician) see it — requesters never do
The NetManager containers must be running: docker compose --profile netmanager up -d

"License invalid/expired" but I've paid

The instance re-validates daily and tolerates up to 14 days offline — beyond that it needs to reach the license service. Check outbound connectivity.
Restart the API to force an immediate re-validation: docker compose restart api
Still stuck? Your license key and instance details are on Settings → License — contact support with those.

Performance & data

Everything is slow

docker stats — is the host out of RAM/CPU?
PostgreSQL and Redis live on the same host; heavy report queries on tiny hardware will show. 2 CPU / 4 GB is the working minimum.

I need to inspect the database

docker compose exec db psql -U "$POSTGRES_USER" "$POSTGRES_DB"

The DB is bound to localhost only — this is the supported access path.

Getting help

Still stuck? Collect the following before contacting support — it halves the round-trips:

docker compose ps > support-bundle.txt
docker compose logs --since 1h api worker beat >> support-bundle.txt

You can also grant time-boxed Support Access so we can look with you.