open-notebook/docs/6-TROUBLESHOOTING/quick-fixes.md

Quick Fixes - Top 11 Issues & Solutions

Common problems with 1-minute solutions.

---

#1: "Cannot connect to server"

Symptom: Browser shows error "Cannot connect to server" or "Unable to reach API"

Cause: Frontend can't reach API

Solution (1 minute):

# Step 1: Check if API is running
docker ps | grep api

# Step 2: Verify port 5055 is accessible
curl http://localhost:5055/health

# Expected output: {"status":"ok"}

# If that doesn't work:
# Step 3: Restart services
docker compose restart

# Step 4: Try again
# Open http://localhost:8502 in browser

If still broken:

• Check API_URL in .env (should match your frontend URL)
• See Connection Issues

---

#2: "Invalid API key" or "Models not showing"

Symptom: Settings → Models shows "No models available"

Cause: No credential configured, or credential has invalid API key

Solution (1 minute):

1. Go to Settings → API Keys
2. If no credential exists, click "Add Credential" and add one
3. If a credential exists, click "Test Connection"
4. If test fails, delete and re-create with correct key
5. After test passes, click "Discover Models" → "Register Models"
6. Go to Settings → Models to verify models appear

If still broken:

• Make sure key has no extra spaces
• Generate a fresh key from provider dashboard
• Check that OPEN_NOTEBOOK_ENCRYPTION_KEY is set in docker-compose.yml
• See AI & Chat Issues

---

#3: "Port X already in use"

Symptom: Docker error "Port 8502 is already allocated"

Cause: Another service using that port

Solution (1 minute):

# Option 1: Stop the other service
# Find what's using port 8502
lsof -i :8502
# Kill it or close the app

# Option 2: Use different port
# Edit docker-compose.yml
# Change: - "8502:8502"
# To:     - "8503:8502"

# Then restart
docker compose restart
# Access at: http://localhost:8503

---

#4: "Cannot process file" or "Unsupported format"

Symptom: Upload fails or says "File format not supported"

Cause: File type not supported or too large

Solution (1 minute):

# Check if file format is supported:
# ✓ PDF, DOCX, PPTX, XLSX (documents)
# ✓ MP3, WAV, M4A (audio)
# ✓ MP4, AVI, MOV (video)
# ✓ URLs/web links

# ✗ Pure images (.jpg without OCR)
# ✗ Files > 100MB

# Try these:
# - Convert to PDF if possible
# - Split large files
# - Try uploading again

---

#5: "Chat is very slow"

Symptom: Chat responses take minutes or timeout

Cause: Slow AI provider, large context, or overloaded system

Solution (1 minute):

# Step 1: Check which model you're using
# Settings → Models
# Note the model name

# Step 2: Try a cheaper/faster model
# OpenAI: Switch to gpt-4o-mini (10x cheaper, slightly faster)
# Anthropic: Switch to claude-3-5-haiku (fastest)
# Groq: Use any model (ultra-fast)

# Step 3: Reduce context
# Chat: Select fewer sources
# Use "Summary Only" instead of "Full Content"

# Step 4: Check if API is overloaded
docker stats
# Look at CPU/memory usage

For deep dive: See AI & Chat Issues

---

#6: "Chat gives bad responses"

Symptom: AI responses are generic, wrong, or irrelevant

Cause: Bad context, vague question, or wrong model

Solution (1 minute):

# Step 1: Make sure sources are in context
# Click "Select Sources" in Chat
# Verify relevant sources are checked and set to "Full Content"

# Step 2: Ask a specific question
# Bad: "What do you think?"
# Good: "Based on the paper's methodology section, what are the 3 main limitations?"

# Step 3: Try a more powerful model
# OpenAI: Use gpt-4o (better reasoning)
# Anthropic: Use claude-3-5-sonnet (best reasoning)

# Step 4: Check citations
# Click citations to verify AI actually saw those sources

For detailed help: See Chat Effectively

---

#7: "Search returns nothing"

Symptom: Search shows 0 results even though content exists

Cause: Wrong search type or poor query

Solution (1 minute):

# Try a different search type:

# If you searched with KEYWORDS:
# Try VECTOR SEARCH instead
# (Concept-based, not keyword-based)

# If you searched for CONCEPTS:
# Try TEXT SEARCH instead
# (Look for specific words in your query)

# Try simpler search:
# Instead of: "How do transformers work in neural networks?"
# Try: "transformers" or "neural networks"

# Check sources are processed:
# Go to notebook
# All sources should show green "Ready" status

For detailed help: See Search Effectively

---

#8: "Podcast generation failed"

Symptom: "Podcast generation failed" error

Cause: Insufficient content, API quota, or network issue

Solution (1 minute):

# Step 1: Make sure you have content
# Select at least 1-2 sources
# Avoid single-sentence sources

# Step 2: Try again
# Sometimes it's a temporary API issue
# Wait 30 seconds and retry

# Step 3: Check your TTS provider has quota
# OpenAI: Check account has credits
# ElevenLabs: Check monthly quota
# Google: Check API quota

# Step 4: Try different TTS provider
# In podcast generation, choose "Google" or "Local"
# instead of "ElevenLabs"

For detailed help: See FAQ

---

#9: "Services won't start" or Docker error

Symptom: Docker error when running docker compose up

Cause: Corrupt configuration, permission issue, or resource issue

Solution (1 minute):

# Step 1: Check logs
docker compose logs

# Step 2: Try restart
docker compose restart

# Step 3: If that fails, rebuild
docker compose down
docker compose up --build

# Step 4: Check disk space
df -h
# Need at least 5GB free

# Step 5: Check Docker has enough memory
# Docker settings → Resources → Memory: 4GB+

---

#10: "Database says 'too many connections'"

Symptom: Error about database connections

Cause: Too many concurrent operations

Solution (1 minute):

# In .env, reduce concurrency:
SURREAL_COMMANDS_MAX_TASKS=2

# Then restart:
docker compose restart

# This makes it slower but more stable

---

#11: Slow Startup or Download Timeouts (China/Slow Networks)

Symptom: Container crashes on startup, worker enters FATAL state, or pip/uv downloads fail

Cause: Slow network or restricted access to Python package repositories

Solution:

Increase Download Timeout

# In docker-compose.yml environment:
environment:
  - UV_HTTP_TIMEOUT=600  # 10 minutes (default is 30s)

Use Chinese Mirrors (if in China)

environment:
  - UV_HTTP_TIMEOUT=600
  - UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
  - PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple

Alternative Chinese mirrors:

• Tsinghua: https://pypi.tuna.tsinghua.edu.cn/simple
• Aliyun: https://mirrors.aliyun.com/pypi/simple/
• Huawei: https://repo.huaweicloud.com/repository/pypi/simple

Note: First startup may take several minutes while dependencies download. Subsequent starts will be faster.

---

Quick Troubleshooting Checklist

When something breaks:

• Restart services: docker compose restart
• Check logs: docker compose logs
• Verify connectivity: curl http://localhost:5055/health
• Check .env: API keys set? API_URL correct?
• Check resources: docker stats (CPU/memory)
• Clear cache: docker system prune (free space)
• Rebuild if needed: docker compose up --build

---

Nuclear Options (Last Resort)

Completely reset (will lose all data in Docker):

docker compose down -v
docker compose up --build

Reset to defaults:

# Backup your .env first!
cp .env .env.backup

# Reset to example
cp .env.example .env

# Edit with your API keys
# Restart
docker compose up

---

Prevention Tips

1. Keep backups — Export your notebooks regularly
2. Monitor logs — Check docker compose logs periodically
3. Update regularly — Pull latest image: docker pull lfnovo/open_notebook:latest
4. Document changes — Keep notes on what you configured
5. Test after updates — Verify everything works

---

Still Stuck?

• Look up your exact error in Troubleshooting Index
• Check the FAQ in FAQ
• Check logs: docker compose logs | head -50
• Ask for help: Discord or GitHub Issues