open-notebook/docs/6-TROUBLESHOOTING/index.md

Troubleshooting - Problem Solving Guide

Having issues? Use this guide to diagnose and fix problems.

---

How to Use This Guide

Step 1: Identify your problem

• What's the symptom? (error message, behavior, something not working?)
• When did it happen? (during install, while using, after update?)

Step 2: Find the right guide

• Look below for your symptom
• Go to the specific troubleshooting guide

Step 3: Follow the steps

• Guides are organized by symptom, not by root cause
• Each has diagnostic steps and solutions

---

Quick Problem Map

During Installation

• Docker won't start → Quick Fixes
• Port already in use → Quick Fixes
• Permission denied → Quick Fixes
• Can't connect to database → Connection Issues

When Starting

• API won't start → Quick Fixes
• Frontend won't load → Connection Issues
• "Cannot connect to server" error → Connection Issues

Settings / Configuration

• Models not showing → AI & Chat Issues
• "Invalid API key" → AI & Chat Issues
• Can't find Settings → Quick Fixes

Using Features

• Chat not working → AI & Chat Issues
• Chat responses are slow → AI & Chat Issues
• Chat gives bad answers → AI & Chat Issues

Adding Content

• Can't upload PDF → Quick Fixes
• File won't process → Quick Fixes
• Web link won't extract → Quick Fixes

Search

• Search returns no results → Quick Fixes
• Search returns wrong results → Quick Fixes

Podcasts

• Can't generate podcast → Quick Fixes
• Podcast shows "FAILED" badge → Check the error message displayed on the episode, then use the Retry button. See Podcasts Explained
• Podcast audio is robotic → Quick Fixes
• Podcast generation times out → Quick Fixes

---

Troubleshooting by Error Message

"Cannot connect to server"

→ Connection Issues — Frontend can't reach API

"Invalid API key"

→ AI & Chat Issues — Wrong or missing API key

"Models not available"

→ AI & Chat Issues — Model not configured

"Connection refused"

→ Connection Issues — Service not running or port wrong

"Port already in use"

→ Quick Fixes — Port conflict

"Permission denied"

→ Quick Fixes — File permissions issue

"Unsupported file type"

→ Quick Fixes — File format not supported

"Processing timeout"

→ Quick Fixes — File too large or slow processing

---

Troubleshooting by Component

Frontend (Browser/UI)

• Can't access UI → Connection Issues
• UI is slow → Quick Fixes
• Button/feature missing → Quick Fixes

API (Backend)

• API won't start → Quick Fixes
• API errors in logs → Quick Fixes
• API is slow → Quick Fixes

Database

• Can't connect to database → Connection Issues
• Data lost after restart → FAQ

AI / Chat

• Chat not working → AI & Chat Issues
• Bad responses → AI & Chat Issues
• Cost too high → AI & Chat Issues

Sources

• Can't upload file → Quick Fixes
• File won't process → Quick Fixes

Podcasts

• Won't generate → Quick Fixes
• Bad audio quality → Quick Fixes

---

Diagnostic Checklist

When something isn't working:

• Check if services are running: docker ps
• Check logs: docker compose logs api (or frontend, surrealdb)
• Verify ports are exposed: netstat -tlnp or lsof -i :5055
• Test connectivity: curl http://localhost:5055/health
• Check environment variables: docker inspect <container>
• Try restarting: docker compose restart
• Check firewall/antivirus isn't blocking

---

Getting Help

If you can't find the answer here:

1. Check the relevant guide — Read completely, try all steps
2. Check the FAQ — Frequently Asked Questions
3. Search our Discord — Others may have had same issue
4. Check logs — Most issues show error messages in logs
5. Report on GitHub — Include error message, steps to reproduce

How to Report an Issue

Include:

1. Error message (exact)
2. Steps to reproduce
3. Logs: docker compose logs
4. Your setup: Docker/local, provider, OS
5. What you've already tried

→ Report on GitHub

---

Guides

Quick Fixes

Top 10 most common issues with 1-minute solutions.

Connection Issues

Frontend can't reach API, network problems.

AI & Chat Issues

Chat not working, bad responses, slow performance.

FAQ

Frequently asked questions about usage, costs, and best practices.

---

Common Solutions

Service won't start?

# Check logs
docker compose logs

# Restart everything
docker compose restart

# Nuclear option: rebuild
docker compose down
docker compose up --build

Port conflict?

# Find what's using port 5055
lsof -i :5055
# Kill it or use different port

Can't connect?

# Test API directly
curl http://localhost:5055/health
# Should return: {"status":"ok"}

Slow performance?

# Check resource usage
docker stats

# Reduce concurrency in .env
SURREAL_COMMANDS_MAX_TASKS=2

High costs?

# Switch to cheaper model
# In Settings → Models → Choose gpt-4o-mini (OpenAI)
# Or use Ollama (free)

---

Still Stuck?

Before asking for help:

1. Read the relevant guide completely
2. Try all the steps
3. Check the logs
4. Restart services
5. Search existing issues on GitHub

Then:

• Discord: https://discord.gg/37XJPXfz2w (fastest response)
• GitHub Issues: https://github.com/lfnovo/open-notebook/issues