Troubleshooting

Authentication

"Authentication failed" when opening a document

• Verify JWT is generated correctly (no empty/expired token).
• Ensure TOKEN_SECRET matches in both Next.js and Hocuspocus.
• Confirm AUTH_URL matches the site URL and AUTH_SECRET is set and persistent.
• If using a reverse proxy, check cookie domain/secure flags and time sync.

Documents not saving

• Ensure the Hocuspocus collaboration server is running.
• If using PostgreSQL, verify DATABASE_URL (or POSTGRES_URL / POSTGRES_DIRECT_URL).
• With SQLite, ensure the /prisma volume is mounted (Docker) to persist writes.
• Check Hocuspocus logs for save errors.
• Apply schema: npm run db:push.

Collaboration not working

• Verify NEXT_PUBLIC_HOCUSPOCUS_URL is accessible from the browser.
• If your site is HTTPS, use wss:// for the Hocuspocus URL.
• Open firewall/ports (default 1234), and enable WebSocket upgrade in proxies.

Provider issues (OpenAI, OpenRouter, Ollama)

• Set provider env vars: OPENAI_API_KEY, OPENROUTER_API_KEY, OLLAMA_HOST.
• Test connectivity with curl/Postman; check for 401/429 or region restrictions.
• For Ollama, ensure the daemon is running (default http://localhost:11434).

Browserless

• Provide BROWSERLESS_URL or BROWSERLESS_TOKEN.
• 401/403 usually indicate invalid token or wrong workspace scope.

Docker gotchas

• Persist SQLite by mounting /prisma.
• AUTH_URL must match the public URL; mismatches break login callbacks.
• Switch to PostgreSQL with DB=postgres and a valid DATABASE_URL.
• Changing ports: set PORT and update the -p host:container mapping consistently.

Vercel deployment

• Use PostgreSQL for production; SQLite is read-only on Vercel.
• Set AUTH_URL to your Vercel domain and AUTH_SECRET.
• If using collaboration, set NEXT_PUBLIC_HOCUSPOCUS_URL to a reachable wss:// endpoint.

Ports already in use

• Change PORT (e.g., PORT=3001) and update Docker/Compose mappings, or free the port.

Getting logs

• Next.js: npm run dev (terminal output shows route and server errors).
• Hocuspocus: check its process/container logs for auth/save issues.
• Docker: docker logs openchat to inspect runtime errors.

Need help?

• Discord: https://discord.gg/WQnmggQknM
• Issues: https://github.com/openchatui/openchat/issues