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.

Still Stuck?

If you encounter a bug not listed here, please report it via the Alpha Feedback Form. Include:

  • Your OS (Mac/Windows)
  • A screenshot of the error
  • The text from your Backend Terminal