Troubleshooting

Solutions to common issues with Jack The Butler.

Having issues? Find solutions to common problems below.

Installation Issues

Database resets after redeployment

Cause: No persistent volume configured.

Solution: Mount a volume to /app/data. See Volume Configuration.

"Cannot find module" error on startup

Cause: Dependencies not installed.

Solution: Run pnpm install or rebuild Docker image.

Port already in use

Cause: Another process using port 3000.

Solution: Change the PORT environment variable or stop the other process.

Login Issues

Can't login with default credentials

Default credentials:

If these don't work, the default admin may have been disabled. You'll need to:

  1. Access the database directly (SQLite)
  2. Reset the admin password or create a new admin

Forgot password

Jack doesn't have email-based password reset. Ask an admin to reset your password in Settings → Staff, or access the database directly.

Session keeps expiring

Cause: JWT tokens expire after 24 hours.

Solution: This is expected behavior. Login again to get a new token.

AI Issues

AI responses are slow

Causes and solutions:

  • Local AI first load — Models load on first use. Subsequent responses are faster.
  • Cloud AI latency — Check your internet connection. Consider using a smaller model (Haiku/mini).
  • Large knowledge base — Optimize entries, remove duplicates.

AI gives wrong information

Solutions:

  • Check your knowledge base for incorrect entries
  • Add more specific entries for the topic
  • Use "Suggest" mode to review responses before sending

"API key invalid" error

Causes:

  • Key copied incorrectly (extra spaces)
  • Key expired or revoked
  • Insufficient API credits

Solution: Generate a new API key and reconfigure in Settings → Apps.

Local AI not working

Causes:

  • Insufficient RAM (needs ~2GB)
  • Model download failed

Solution: Check server has enough memory. Restart Jack to retry model download.

Channel Issues

WhatsApp messages not arriving

Check:

  • Webhook URL is correct in Meta Business settings
  • Webhook subscription includes "messages" field
  • Access token hasn't expired
  • Jack is accessible from the internet (HTTPS required)

WhatsApp sending fails

Causes:

  • Replying after 24-hour window (need message template)
  • Phone number format incorrect
  • Business verification incomplete

SMS not working

Check:

  • Twilio credentials are correct
  • Twilio account has sufficient funds
  • Phone number has SMS capability
  • Webhook URL configured in Twilio

Email connection fails

Solutions:

  • Verify IMAP/SMTP settings from your provider
  • Use app password (not regular password) for Gmail/Outlook
  • Ensure IMAP is enabled in email settings
  • Check firewall allows outbound connections on ports 993/587

Dashboard Issues

Dashboard won't load

Check:

  • Clear browser cache and cookies
  • Try incognito/private mode
  • Check browser console for errors
  • Verify Jack is running (curl http://localhost:3000/health)

Real-time updates not working

Cause: WebSocket connection failed.

Solutions:

  • Check reverse proxy passes WebSocket headers
  • Verify firewall allows WebSocket connections
  • Try refreshing the page

Search returns no results

Cause: Search index not built.

Solution: Search indexes after build. Wait for indexing to complete after adding content.

Performance Issues

High memory usage

Causes:

  • Local AI models loaded (normal, ~2GB)
  • Large conversation history
  • Memory leak (report as bug)

Solutions:

  • Use cloud AI instead of local
  • Archive old conversations
  • Increase server RAM

Database growing too large

Solutions:

  • Archive or delete old conversations
  • Remove unused knowledge base entries
  • Run VACUUM on SQLite database

Getting More Help

If your issue isn't listed here:

  1. Check GitHub Discussions for similar issues
  2. Search GitHub Issues
  3. Open a new issue with:
    • Jack version
    • Deployment method (Docker, cloud, source)
    • Steps to reproduce
    • Error messages or logs