Troubleshooting Guide

Common issues and how to fix them.

Startup Issues

“Address already in use”

Error: [Errno 48] Address already in use. Cause: You have another instance of the backend running, or another app is using port 8000. Fix:

  1. Close your terminal windows.
  2. Run lsof -i :8000 (on Mac) to find the process ID.
  3. Run kill -9 <PID> to kill it.
  4. Restart the backend.

“Cannot connect to server”

Symptom: The frontend loads, but shows a red disconnected icon or infinite loading spinners. Cause: The backend terminal is closed or not running. Fix: Ensure you have the Backend Terminal (Step 1 of Installation) running and showing “Application startup complete”.

Workflow Issues

“NotebookLM outputs feel generic”

Symptom: The deepening files don’t sound like your story. Cause: NotebookLM doesn’t know your story constraints yet. Fix:

  1. Ensure Story_Skeleton.md is added as a Source in your notebook.
  2. In your prompt, explicitly reference the skeleton: “Using my Story Skeleton (specifically the protagonist’s flaw ‘Hubris’), please generate…”

“Import completed but ingredient inventory is 0”

Symptom: You dragged files in, the progress bar finished, but the Research Graph is empty. Cause: The files might be empty or formatted incorrectly. Fix:

  1. Open your .md files and ensure they contain text.
  2. Ensure you clicked the Commit button after the preview stage. Markdown files in the preview are candidates, not yet ingested.

“I can’t pick a concept”

Symptom: The Concept Generator creates 5 concepts but none feel “right”. Cause: Conflict isn’t baked into the ingredients. Fix:

  1. Your ingredients might be missing a Hard World Rule or a Real Antagonist.
  2. Return to NotebookLM, create a “Villain Support” notebook, export it, and add it to the Codex.
  3. Re-run the extraction.

Platform-Specific Issues (Windows/Linux)

The app was developed on macOS. If you’re running on Windows or Linux and had to make changes to get it working, please report your fix so we can improve cross-platform support for everyone.

How to Report a Platform Fix

  1. Go to the GitHub Issues page
  2. Select “Platform Compatibility Fix”
  3. Fill out the form:
    • What platform you’re on
    • What error you encountered
    • What file(s) you changed
    • What the fix was
    • Whether it still works on other platforms (if you know)

What Makes a Good Fix Report

Good examples:

  • “Added pyreadline3 to requirements.txt because Windows doesn’t have readline”
  • “Changed path separator in path_manager.py from / to os.sep”
  • “Made kokoro-onnx optional because it fails to build on some Linux distros”

Not helpful:

  • “I changed some stuff and it works now”
  • Hardcoding paths like C:\Users\MyName\...
  • Removing features to make it run

What Happens Next

The maintainers will:

  1. Review your fix
  2. Implement it properly with cross-platform guards
  3. Credit you in the commit message
  4. Push to main so everyone benefits

Still Stuck?

If you encounter a bug not listed here, please report it via GitHub Issues. Include:

  • Your OS (Windows/Linux/Mac) and version
  • Python version (python --version)
  • A screenshot of the error
  • The text from your Backend Terminal