ContextQMD
Back to Open Notebook

Troubleshooting - Problem Solving Guide

docs/6-TROUBLESHOOTING/index.md

1.8.57.2 KB
Original Source

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

When Starting

Settings / Configuration

Using Features

Adding Content

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)

API (Backend)

Database

AI / Chat

Sources

Podcasts

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?

bash
# Check logs
docker compose logs

# Restart everything
docker compose restart

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

Port conflict?

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

Can't connect?

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

Slow performance?

bash
# Check resource usage
docker stats

# Reduce concurrency in .env
SURREAL_COMMANDS_MAX_TASKS=2

High costs?

bash
# 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: