open-notebook/docs/troubleshooting/quick-fixes.md

5-Minute Troubleshooting

Problem: Something isn't working? Let's fix it fast.

Start Here: What's Your Issue?

Click your problem:

1. "Unable to connect to server" or blank page

2. Container won't start or crashes

3. Works on server but not from my computer

4. API or authentication errors

5. Slow or timeout errors

---

Fix: "Unable to connect to server"

This means your frontend can't reach the API. 99% of the time, this is an API_URL problem.

Step-by-Step Fix:

1. Check if API is running:

   curl http://localhost:5055/health
   # Should return: {"status": "healthy"} or similar
   

   • ❌ Connection refused? → Port 5055 is not exposed. Jump to port fix
   • ✅ Got response? → API is running, continue below.

2. Are you accessing from a different machine?

   • Your browser on Computer A
   • Docker running on Computer B (server, Raspberry Pi, NAS, etc.)

   → You MUST set API_URL

   Find your server's IP:

   # On the server running Docker:
   hostname -I    # Linux
   ipconfig       # Windows
   ifconfig       # Mac
   

   Set API_URL (replace 192.168.1.100 with YOUR server IP):

   Docker Compose - Add to your docker-compose.yml:

   environment:
     - OPENAI_API_KEY=your_key
     - API_URL=http://192.168.1.100:5055
   

   Docker Run - Add this flag:

   -e API_URL=http://192.168.1.100:5055
   

   Then restart:

   docker compose down && docker compose up -d
   # or for docker run, stop and restart the container
   

3. Still not working?

   Check what URL your browser is trying to access:

   • Open browser DevTools (F12)
   • Go to Network tab
   • Refresh the page
   • Look for failed requests to /api/config

   The URL should match: http://YOUR_SERVER_IP:5055/api/config

   If it shows localhost:5055 or wrong IP, your API_URL is not set correctly.

Fix: Port 5055 Not Exposed

Check currently exposed ports:

docker ps
# Look for: 0.0.0.0:5055->5055

Not there? Add it:

Docker Compose - Update your docker-compose.yml:

services:
  open_notebook:
    ports:
      - "8502:8502"
      - "5055:5055"  # Add this line!

Docker Run - Add -p 5055:5055:

docker run -d \
  -p 8502:8502 \
  -p 5055:5055 \  # Add this!
  # ... rest of your command

Then restart the container.

---

Fix: Container Won't Start

Check the logs:

docker logs open-notebook
# or
docker compose logs

Common causes:

Error Message	Fix
"Port already in use"	Change port: -p 8503:8502 or stop conflicting service
"Permission denied"	Add user to docker group: sudo usermod -aG docker $USER (then log out/in)
"Invalid API key"	Check OPENAI_API_KEY in environment variables
"Out of memory"	Increase Docker memory limit to 2GB+ in Docker Desktop settings
"No such file or directory"	Check volume paths exist and are accessible

Quick reset:

docker compose down -v
docker compose up -d

---

Fix: Works on Server But Not From My Computer

Symptom: Open Notebook works when accessed on the server itself (localhost:8502) but not from another computer.

This is 100% an API_URL problem.

✅ The Fix:

Your API_URL must match the URL you use to access Open Notebook.

You access via	Set API_URL to
http://192.168.1.50:8502	http://192.168.1.50:5055
http://myserver:8502	http://myserver:5055
http://10.0.0.5:8502	http://10.0.0.5:5055

Apply the fix:

1. Edit your docker-compose.yml:

   environment:
     - OPENAI_API_KEY=your_key
     - API_URL=http://YOUR_SERVER_IP_OR_HOSTNAME:5055
   

2. Or edit your docker.env file:

   API_URL=http://YOUR_SERVER_IP_OR_HOSTNAME:5055
   

3. Restart:

   docker compose down && docker compose up -d
   

Common mistakes:

• ❌ Using localhost in API_URL when accessing remotely
• ❌ Using your client computer's IP instead of the server's IP
• ❌ Adding /api to the end (it's automatic)

---

Fix: API or Authentication Errors

"Missing authorization header"

You have password auth enabled. Make sure it's set correctly:

environment:
  - OPEN_NOTEBOOK_PASSWORD=your_password

Or provide the password when logging into the web interface.

"API config endpoint returned status 404"

You added /api to API_URL. Remove it:

❌ Wrong: API_URL=http://192.168.1.100:5055/api

✅ Correct: API_URL=http://192.168.1.100:5055

The /api path is added automatically by the application.

"Invalid API key" or "Incorrect API key"

1. Check key format (OpenAI keys start with sk-)
2. Verify you have credits in your provider account
3. Check for spaces around the key in your .env file:

   # Wrong - has spaces
   OPENAI_API_KEY = sk-your-key
   
   # Correct
   OPENAI_API_KEY=sk-your-key
   

4. Test your key directly:

   curl https://api.openai.com/v1/models \
     -H "Authorization: Bearer YOUR_KEY"
   

---

Fix: Slow or Timeout Errors

Increase timeouts for local models:

If you're using Ollama or LM Studio:

environment:
  - API_CLIENT_TIMEOUT=600  # 10 minutes
  - ESPERANTO_LLM_TIMEOUT=180  # 3 minutes

Recommended timeouts by setup:

• Cloud APIs (OpenAI, Anthropic): Default (300s)
• Local Ollama with GPU: 600s
• Local Ollama with CPU: 1200s
• Remote LM Studio: 900s

Use faster models:

• Cloud APIs: OpenAI, Anthropic, Groq (fastest)
• Local models: Try smaller models first
  • Fast: gemma2:2b, phi3:mini
  • Medium: llama3:8b, mistral:7b
  • Slow: llama3:70b, mixtral:8x7b

Preload local models:

# This prevents first-run delays
ollama run llama3
# Press Ctrl+D to exit after model loads

---

Still Stuck?

Collect diagnostics:

# Container status
docker ps

# Container logs (last 100 lines)
docker logs --tail 100 open-notebook > logs.txt

# Or for docker compose
docker compose logs --tail 100 > logs.txt

# Check resource usage
docker stats --no-stream

Get help:

1. Discord - Fastest response from community
2. GitHub Issues - Bug reports and features
3. Full Troubleshooting Guide - More detailed solutions

Before asking:

• Include your docker-compose.yml (remove API keys!)
• Include relevant logs
• Describe your setup (local vs remote, OS, Docker version)
• What you've already tried

---

Quick Reference: API_URL Settings

Scenario	API_URL Value	Example
Local access only	Not needed	Leave unset
Remote on same network	http://SERVER_IP:5055	http://192.168.1.100:5055
Remote with hostname	http://HOSTNAME:5055	http://myserver.local:5055
Behind reverse proxy (no SSL)	http://DOMAIN:5055	http://notebook.local:5055
Behind reverse proxy (SSL)	https://DOMAIN/api	https://notebook.example.com/api

Remember: The API_URL is from your browser's perspective, not the server's!