Troubleshooting

Most reported problems are data or configuration issues, not infrastructure. Start with the health triage, then check the tables below for where users actually get stuck.

The 30-second health triage

curl -fsS http://localhost:3000/api/health   # app: expect database:ok, orchestrator:ok
docker compose ps                            # all services "Up"/healthy?
docker compose logs --tail=100 app           # recent app errors

If /api/health returns 200 with database:ok and orchestrator:ok, the platform is up.

Install / first run

• Install seems to hang for many minutes — it's the one-time model download (several GB). Watch progress with docker compose logs -f python-orchestrator.
• GPU device errors on Linux — install the NVIDIA Container Toolkit, or run with a cloud model provider instead.
• Port 3000 already in use — stop the other service or change the published port in docker-compose.yml.
• App loads unstyled — usually a proxy/cache issue; hard-refresh and check the reverse proxy passes static assets.

License

• License won't activate — check the key was pasted exactly as emailed (it's a three-part signed token).
• “License expired” on a new key — check the host clock for skew.
• Seat limit reached — expected behavior; raise the tier or remove members.

AI quality & performance

• First answer is slow — model cold start (loading into VRAM); subsequent calls are fast.
• Consistently slow — GPU too small for the chosen model; pick a smaller model or a cloud provider for heavy tasks.
• “I couldn't find that in the knowledge base” — grounding working as intended; add the missing document and retry.
• Wrong or stale citations — re-ingest; newer documents supersede older near-duplicates automatically.

Export

• Export button disabled — export is gated until blocking checklist items (unanswered questions, go/no-go) are complete.
• Word/PowerPoint generation fails — check the orchestrator is healthy: docker compose logs -f python-orchestrator.

Before contacting support

1. 1Run the health triage above and capture the output.
2. 2Collect docker compose logs --tail=200 app python-orchestrator.
3. 3Note the exact action, any error code shown, and whether you're on local or cloud models.