Troubleshooting

Common issues and how to fix them. Can't find your answer? Open an issue on GitHub

⚠️Backend won't start

Symptoms:

  • •App shows 'Backend disconnected' error
  • •Sidecar process not starting
  • •API calls fail with connection refused

✓Check if sidecar is running

  1. 1.Open Task Manager (Ctrl+Shift+Esc)
  2. 2.Look for 'HuluChat Backend' or 'python' process
  3. 3.If not running, manually start it backend

✓Restart the application

  1. 1.Close HuluChat completely
  2. 2.Reopen HuluChat
  3. 3.The backend should auto-start

✓Check antivirus/firewall

  1. 1.Some antivirus software blocks the sidecar
  2. 2.Add an exception for HuluChat in your antivirus
  3. 3.Allow the app through firewall

⚠️API Key not working

Symptoms:

  • •Error: 'Invalid API key'
  • •Error: 'Authentication failed'
  • •AI responds with error message

✓Verify API key format

  1. 1.Make sure the API key is correct (no extra spaces)
  2. 2.Check if the key starts with 'sk-' for OpenAI
  3. 3.Some providers use different prefixes

✓Check Base URL

  1. 1.Verify the Base URL is correct for your provider
  2. 2.OpenAI: https://api.openai.com/v1
  3. 3.DeepSeek: https://api.deepseek.com
  4. 4.Ollama: http://localhost:11434/v1

✓Test API key

  1. 1.Go to Settings
  2. 2.Click 'Test Connection' button
  3. 3.A successful test confirms your key works

⚠️Slow performance

Symptoms:

  • •App feels sluggish
  • •Long loading times
  • •High memory usage

✓Clear old sessions

  1. 1.Delete unused sessions from sidebar
  2. 2.Use folders to organize
  3. 3.Large session counts slow down the app

✓Check system resources

  1. 1.Close other heavy applications
  2. 2.Restart the app if memory is low
  3. 3.Consider upgrading RAM

⚠️RAG not working

Symptoms:

  • •Documents not loading
  • •Search returns no results
  • •Error messages about embeddings

✓Check document format

  1. 1.Ensure document is in supported format (PDF, TXT, MD)
  2. 2.Very large PDFs may take longer to process
  3. 3.Try splitting large documents

✓Restart after adding documents

  1. 1.Remove and re-add documents
  2. 2.Wait for processing to complete
  3. 3.Check the console for errors

Still Having Issues?

If you above solutions don't resolve your problem, here are additional steps:

📋 Check Logs

Open Developer Tools (F12) and check the Console tab for error messages.

🔄 Reinstall

Download the latest version from GitHub. A clean reinstall often fixes issues.

💬 Get Help

Create an issue on GitHub with details about your setup and the problem.

← FAQBack to Docs →