Troubleshooting Guide

Troubleshooting Guide

Solutions for common problems in the EPIC application. Written for all skill levels.

Table of Contents

Quick Diagnosis

Use this flowchart to find your problem:

Which Service Does What?

Service Port What It Does How to Start
Frontend 3000 The website you see in your browser cd frontend && npm run dev
Backend 3001 Saves your data (novels, characters, etc.) cd backend && npm run dev
AI Service 8000 Powers the AI chat and writing tools cd aiservice && uv run python -m api.main

Think of it like a restaurant:

  • Frontend = The dining room (what customers see)
  • Backend = The kitchen (where food is prepared and stored)
  • AI Service = A specialist chef (handles complex AI cooking)

Service Won't Start

Frontend Won't Start (Port 3000)

What you'll see:

  • Browser shows "This site can't be reached"
  • Terminal shows errors when running npm run dev

Common causes and fixes:

1. Missing Dependencies

What this means: The code needs other code to work, and that other code isn't installed.

Fix:

cd frontend
npm install

Then try starting again:

npm run dev

2. Port Already in Use

What this means: Another program is already using port 3000.

You'll see an error like:

Error: listen EADDRINUSE: address already in use :::3000

Fix: See Port Conflicts section below.

3. Node.js Not Installed

What this means: Your computer doesn't have the program needed to run JavaScript.

Check if you have it:

node --version

If you see "command not found", download Node.js from https://nodejs.org

Backend Won't Start (Port 3001)

What you'll see:

  • Frontend loads but shows "Failed to fetch" errors
  • Can't save or load novels
  • Terminal shows errors when running npm run dev in backend folder

Common causes and fixes:

1. Missing Dependencies

cd backend
npm install

2. Database Not Set Up

What this means: The database structure hasn't been created yet.

Fix:

cd backend
npx prisma db push
npx prisma generate

3. Database File Corrupted

What this means: The file storing your data got damaged.

Fix (WARNING: This deletes your data):

cd backend
del epic.db          # Windows
rm epic.db           # Mac/Linux
npx prisma db push

4. Prisma Client Outdated

What this means: The code that talks to the database is out of date.

Fix:

cd backend
npx prisma generate

AI Service Won't Start (Port 8000)

What you'll see:

  • AI chat doesn't respond
  • "Failed to connect" errors when using AI features
  • Python errors in terminal

Common causes and fixes:

1. Wrong Directory

Make sure you're in the right folder:

cd aiservice

2. Virtual Environment Not Set Up

What this means: Python packages aren't installed in the right place.

Fix:

cd aiservice
uv sync

3. epic_engine Not Installed

What this means: The AI library isn't connected properly.

Fix:

cd aiservice
uv sync --reinstall-package epic-engine

4. Missing Environment Variables

What this means: The AI service needs API keys (passwords) to talk to AI providers.

Check: Make sure you have a .env file in the aiservice folder with your API keys:

OPENAI_API_KEY=sk-your-key-here
ANTHROPIC_API_KEY=sk-ant-your-key-here

5. Port Already in Use

See Port Conflicts section below.

Port Conflicts

What Are Ports?

Think of ports like apartment numbers in a building:

  • Your computer is the building
  • Each program gets its own apartment (port number)
  • Two programs can't live in the same apartment

EPIC uses three apartments:

  • 3000 - Frontend's apartment
  • 3001 - Backend's apartment
  • 8000 - AI Service's apartment

Finding What's Using a Port

Windows (PowerShell):

# Check who's using port 3000
netstat -ano | findstr :3000

# Check who's using port 3001
netstat -ano | findstr :3001

# Check who's using port 8000
netstat -ano | findstr :8000

You'll see something like:

TCP    0.0.0.0:3000    0.0.0.0:0    LISTENING    12345

The last number (12345) is the Process ID (PID) - the program's ID card.

Mac/Linux:

# Check who's using port 3000
lsof -i :3000

Killing a Process

What this means: Force-closing the program that's blocking the port.

Windows:

# Replace 12345 with the PID you found
taskkill /PID 12345 /F

Mac/Linux:

# Replace 12345 with the PID you found
kill -9 12345

Nuclear option - kill ALL Node.js processes:

# Windows - closes everything using Node
taskkill /F /IM node.exe

# Mac/Linux
pkill -f node

⚠️ Warning: This closes ALL Node.js programs, not just EPIC.

Module Not Found Errors

What Does "Module Not Found" Mean?

Your code is trying to use another piece of code, but can't find it. It's like trying to call a friend whose phone number you don't have.

JavaScript/TypeScript Modules

Error looks like:

Module not found: Can't resolve 'some-package'

Fixes:

1. Install Dependencies

cd frontend   # or backend
npm install

2. Install the Specific Package

npm install some-package

3. Clear Cache and Reinstall

# Delete node_modules and reinstall
rd /s /q node_modules   # Windows
rm -rf node_modules     # Mac/Linux

npm install

4. TypeScript Can't Find Types

Error looks like:

Cannot find module './SomeComponent' or its corresponding type declarations

Fix:

# Restart TypeScript
# In VS Code: Ctrl+Shift+P → "TypeScript: Restart TS Server"

Python Modules

Error looks like:

ModuleNotFoundError: No module named 'epic_engine'

Fixes:

1. Sync Dependencies

cd aiservice
uv sync

2. Reinstall epic_engine

cd aiservice
uv sync --reinstall-package epic-engine

3. Check You're Using the Right Python

What this means: Your computer might have multiple Python versions, and VS Code might be looking at the wrong one.

Fix in VS Code:

  1. Press Ctrl+Shift+P
  2. Type "Python: Select Interpreter"
  3. Choose the one in your aiservice/.venv folder

Memory and GPU Issues

Understanding the Problem

The local AI model (Qwen) is like a very big book that needs to be loaded into memory. If your computer doesn't have enough memory, it can't hold the whole book.

Qwen Model Won't Load

Error looks like:

CUDA out of memory
RuntimeError: CUDA error: out of memory

What this means: Your graphics card doesn't have enough memory.

Fixes:

1. Reduce GPU Layers

Edit the config to use fewer GPU layers (more CPU, slower but works):

In epic_engine config:

local:
  n_gpu_layers: 20  # Try reducing from 33 to 20 or lower

2. Close Other Programs

Close anything using your GPU:

  • Games
  • Video editors
  • Other AI tools
  • Extra browser tabs (especially YouTube)

3. Use Cloud Provider Instead

Skip local AI and use OpenAI/Anthropic:

  • Make sure you have API keys in .env
  • The system will automatically use cloud when local fails

Out of Memory Errors

Error looks like:

MemoryError
JavaScript heap out of memory

Fixes:

1. Increase Node.js Memory (for frontend/backend)

# Windows
set NODE_OPTIONS=--max-old-space-size=4096
npm run dev

# Mac/Linux
NODE_OPTIONS=--max-old-space-size=4096 npm run dev

2. Close Other Applications

Free up RAM by closing:

  • Other code editors
  • Browsers with many tabs
  • Chat applications
  • Music streaming apps

3. Restart Your Computer

Sometimes memory gets "stuck" - a restart cleans everything.

Slow AI Responses

What's normal:

  • First response: 5-15 seconds (model loading)
  • Following responses: 2-5 seconds

If it's slower than this:

1. Check GPU Usage

Windows: Open Task Manager → Performance → GPU

If GPU is at 0%, the model is running on CPU (much slower).

2. Make Sure GPU is Being Used

Check AI service startup logs for:

Loading model with 33 GPU layers

If it says 0 GPU layers, your GPU isn't being used.

3. Use a Cloud Provider

Cloud providers (OpenAI, Anthropic) are faster than local Qwen on most consumer hardware.

CORS Errors

What is CORS?

CORS (Cross-Origin Resource Sharing) is a security feature in web browsers.

Simple explanation:

  • Your browser is protective, like a security guard
  • When your frontend (localhost:3000) tries to talk to backend (localhost:3001), the browser asks "Is this allowed?"
  • If the backend doesn't say "yes, this is allowed", the browser blocks the request

What CORS Errors Look Like

In your browser's console (F12 → Console tab):

Access to fetch at 'http://localhost:3001/api/...' from origin
'http://localhost:3000' has been blocked by CORS policy

Fixing CORS Errors

1. Make Sure Backend is Running

The most common cause is the backend isn't running:

cd backend
npm run dev

2. Check Backend CORS Settings

The backend should allow requests from the frontend. This is usually already set up in backend/server.ts.

3. Check You're Using the Right URLs

Make sure frontend is calling:

  • http://localhost:3001 for backend
  • http://localhost:8000 for AI service

Not http://127.0.0.1 or other variations.

4. Clear Browser Cache

Sometimes old settings get stuck:

  1. Open DevTools (F12)
  2. Right-click the refresh button
  3. Select "Empty Cache and Hard Reload"

Build Failures

Frontend Build Fails

When running:

npm run build

1. TypeScript Errors

Error looks like:

Type error: Property 'x' does not exist on type 'y'

Fix: See TypeScript Errors below.

2. Missing Dependencies

npm install

3. Out of Memory During Build

# Windows
set NODE_OPTIONS=--max-old-space-size=4096
npm run build

TypeScript Errors

What is TypeScript? TypeScript is JavaScript with "spell checking" for code. It catches mistakes before you run the program.

Common errors and fixes:

"Property does not exist"

Property 'name' does not exist on type 'User'

What it means: You're trying to use something that doesn't exist.

Fix: Check spelling, or add the property to the type definition.

"Cannot find module"

Cannot find module './Component'

What it means: The file doesn't exist or is named wrong.

Fix:

  • Check the file exists
  • Check the file name matches (case-sensitive!)
  • Restart TypeScript server: Ctrl+Shift+P → "TypeScript: Restart TS Server"

Prisma Errors

"Schema drift"

The database schema is not in sync with your Prisma schema

What it means: The database structure doesn't match what your code expects.

Fix:

cd backend
npx prisma db push

"Migration failed"

Fix:

cd backend
npx prisma migrate reset  # WARNING: Deletes data

Types Not Updating

Fix:

cd backend
npx prisma generate
# Then in VS Code: Ctrl+Shift+P → "TypeScript: Restart TS Server"

Database Issues

Can't Save Data

  1. Check backend is running:

    curl http://localhost:3001/api/health

  2. Check database exists:

    ls backend/epic.db

  3. Rebuild database:

    cd backend
npx prisma db push

Data Disappeared

Your data is stored in backend/epic.db. If this file is deleted, your data is gone.

Prevention: Regularly backup this file:

copy backend\epic.db backend\epic_backup.db   # Windows
cp backend/epic.db backend/epic_backup.db      # Mac/Linux

AI Not Responding Correctly

AI Gives Wrong Information

Cause: The AI might not have your lore synced.

Fix: Resync your novel:

Invoke-RestMethod -Uri "http://localhost:8000/api/sync/novel" `
  -Method POST -ContentType "application/json" `
  -Body '{"novel_id": "YOUR_NOVEL_ID"}'

AI Ignores My Lore

  1. Check sync status:

    curl http://localhost:8000/api/sync/stats

  2. If collection_count is 0: Your novel isn't synced. See above.

  3. Check entities have content:

    • Open npx prisma studio
    • Look at CodexEntry table
    • Make sure fullContent field has text

AI is Very Slow

  1. Use cloud provider instead of local Qwen
  2. Switch to HybridRetriever instead of AdvancedRetriever (faster, slightly less accurate)
  3. Close other GPU-using applications

Emergency Reset

When nothing else works, try these steps in order:

Step 1: Stop Everything

Close all terminals running EPIC services.

# Nuclear option - close all Node and Python
taskkill /F /IM node.exe      # Windows
taskkill /F /IM python.exe    # Windows

pkill -f node                  # Mac/Linux
pkill -f python               # Mac/Linux

Step 2: Clear Caches

# Frontend
cd frontend
rd /s /q node_modules\.next   # Windows
rm -rf node_modules/.next     # Mac/Linux

# Backend Prisma cache
cd backend
rd /s /q node_modules\.prisma # Windows
rm -rf node_modules/.prisma   # Mac/Linux

Step 3: Reinstall Dependencies

# Frontend
cd frontend
npm install

# Backend
cd backend
npm install
npx prisma generate

# AI Service
cd aiservice
uv sync --reinstall-package epic-engine

Step 4: Start Fresh

Open three separate terminals:

Terminal 1 - Backend:

cd backend
npm run dev

Terminal 2 - Frontend:

cd frontend
npm run dev

Terminal 3 - AI Service:

cd aiservice
uv run python -m api.main

Step 5: Verify Everything Works

  1. Open browser to http://localhost:3000 - should see EPIC
  2. Try creating a novel - should save successfully
  3. Open AI chat - should respond

Still Stuck?

If you've tried everything in this guide:

  1. Check the error message carefully - Google the exact error text
  2. Look at the GitHub issues - https://github.com/anthropics/claude-code/issues
  3. Take a break - Sometimes stepping away helps you see the problem clearly
┌─────────────────────────────────────────────────────────────┐
│                    TROUBLESHOOTING CHECKLIST                │
├─────────────────────────────────────────────────────────────┤
│  □ Is the backend running?     (port 3001)                  │
│  □ Is the frontend running?    (port 3000)                  │
│  □ Is the AI service running?  (port 8000)                  │
│  □ Are there error messages in any terminal?                │
│  □ Did you run npm install / uv sync?                       │
│  □ Did you restart after making changes?                    │
│  □ Is your novel synced to vectors?                         │
│  □ Do you have API keys in .env files?                      │
└─────────────────────────────────────────────────────────────┘