Troubleshooting — Lawyer Assistant

Getting started? See QUICKSTART.md first.

0. Quick reference

1. Backend not reachable on port 8765

Symptoms: BootLoader stuck on "loading"; toast/error "Could not reach the backend server. Make sure the Python server is running on port 8765."

Causes & checks:

bash# Is anything listening on 8765?
curl http://localhost:8765/api/health          # expect {"status":"ok",...}
netstat -ano | findstr :8765 | findstr LISTENING   # Windows
lsof -ti:8765                                  # macOS/Linux

If nothing responds, the backend didn't start. Common reasons:

1. Python 3 not on PATH — Electron's venv-manager needs a system Python to create .venv; if it can't find one it falls back to python/python3, which also fails. Verify: python --version.
2. Venv/dependency setup failed — the bridge logs to the Electron console ("Venv setup failed, falling back to system Python"). Fix manually:

bash   python -m venv .venv
   .venv\Scripts\activate        # Windows   |   source .venv/bin/activate
   pip install -r backend/requirements.txt
   python backend/main.py        # run directly to see errors

1. Warmup takes a while — the backend binds the port first, then warms up models in the background, so /api/health should respond quickly. If the process crashes during warmup (OOM, missing model), see §5/§6.

Fix: restart npm run dev (it kills stale listeners and retries). Watch the Electron terminal for Python stdout/stderr.

2. Stale processes on 8765 / 5173

Symptom: EADDRINUSE errors; a previous instance's backend keeps serving old code.

Electron already kills listeners on 8765 and 5173 at startup (frontend/electron/src/main/index.ts → killPort). If you still hit conflicts:

bash# Windows
netstat -ano | findstr :8765 | findstr LISTENING
taskkill /F /PID <pid>

# macOS/Linux
lsof -ti:8765 | xargs kill -9

Then restart the app. See QUICKSTART.md §3.

3. Ollama not running / model unavailable

Symptom: The status/meta line reports model "unavailable"; answers may be generic or missing; direct mode fails.

Causes:

• Ollama isn't started, or isn't on http://localhost:11434 (the default base URL used by OllamaLLM / ChatOllama).
• Ollama is up but the configured model isn't pulled.

Fixes:

bashollama serve                        # ensure the daemon is running
ollama list                         # see pulled models
ollama pull lfm2.5:8b               # pull the launcher's default model

Retrieval still works without Ollama — only LLM generation (RAG answers, relevance verification, scanning) degrades. See BACKEND.md §7.

4. Empty results / "no relevant documents"

Symptom: The agent honestly says it couldn't find relevant information; Sources panel is empty; retrieval returns 0 chunks.

Cause: The corpus was never ingested (empty <project>/workspace/chroma_db for the active project — or no workspace selected at all).

Checks:

bashcurl http://localhost:8765/api/documents    # list indexed files

4a. "No workspace selected"

Symptom: Chat/upload/scan error with "No workspace selected. Select a project folder first."

Cause: A project folder is now required — there is no default data/ folder fallback.

Fix: In the app, click "Work in a folder" and pick the project folder. The backend then stores everything under <project>/workspace/.

4b. Empty workspace index

Fixes:

• In the app: run "Ingest all files" in the Workspace panel (or programmatically curl -X POST http://localhost:8765/api/workspace/ingest) to index every supported document in the folder at once.
• Or attach files individually via the + button (or drag & drop) — uploaded files are ingested automatically.
• Bulk initial ingest of a static corpus (see QUICKSTART.md §4):

bash  .venv\Scripts\activate
  cd backend && python scripts/ingest_all.py            # --reset to rebuild

Also verify the reranker isn't filtering everything: if scores are all below the threshold, try skip_rerank / --no-rerank. See

BACKEND.md §5.

5. Slow first query

Symptom: The first query takes 10–30s; later ones are fast.

Cause: Models (BGE-M3, BGE-Reranker, LLM) load on first use.

Fix: The backend warms up all models in a background thread at startup (backend/main.py), so in the desktop app the first query is already fast after the warmup completes (~seconds after launch). If you run the backend directly and skip warmup, expect a one-time load. Don't kill the app during warmup.

6. GPU out of memory

Symptom: CUDA out of memory during ingestion or embedding.

Fixes:

bashcd backend && python scripts/ingest_all.py --batch-size 32    # lower GPU memory
cd backend && python scripts/ingest_all.py --device cpu       # force CPU

Runtime device is auto-resolved (cuda → mps → cpu) in backend/legal_retrieval/config.py (resolve_device); you can override with PLR_* env vars. See BACKEND.md §5.

7. Frontend dev server failed

Symptom: Electron window shows "⚠️ Frontend Dev Server Failed" and hints cd frontend && npm install.

Fixes:

bashcd frontend && npm install && npm run dev   # confirm Vite starts on 5173

If 5173 is occupied by another app, stop it or restart npm run dev (which kills stale 5173 listeners). See FRONTEND.md §8.

8. Attachments don't work

Symptoms: Files don't upload; uploads fail; attached file ignored.

Checks:

• Supported extensions only (see SUPPORTED_ATTACH_EXTENSIONS in frontend/src/components/Chat/InputBar.tsx).
• Max 5 files per message; 50 docs per folder pick.
• A project folder must be active before uploading (see §4a); /api/upload saves into the project folder itself; check the Electron console for [Upload] logs.
• If all uploads fail and you typed nothing, the app bails out with "No files uploaded."

See FRONTEND.md §2 and BACKEND.md §2.

9. Stream ends without an answer

Symptoms: Answer never arrives; spinner stops; execution log incomplete.

Causes:

• Human-in-the-loop interrupt — the agent paused for approval; the ApprovalBar should appear. Approve or reject to resume (/api/chat/resume). See BACKEND.md §4b.
• SSE hiccup / backend error — the last event was error or the stream closed. The frontend finalizes with whatever it has; retry the query.
• Session expired — resuming an old thread returns "Session expired. Please start a new conversation." (the stored graph was cleaned up).

10. Playbook scan fails / flags missing

Symptoms: Scan errors; zero flags; "Document not found".

Checks:

• The document must be indexed (see §4) before /api/scan/stream can fetch its chunks.
• 50MB upload cap on scan uploads.
• Playbooks come from backend/legal_retrieval/playbook/playbooks/ — if none listed, the default.json may be missing.
• Flags persist to SQLite (playbook/persistence.py); if they don't show, re-run the scan and check /api/flags. See BACKEND.md §6.

11. Diagnostics cheatsheet

bashcurl http://localhost:8765/api/health       # backend alive?
curl http://localhost:8765/api/documents    # indexed files
curl http://localhost:8765/api/playbooks    # available playbooks
curl http://localhost:8765/api/flags        # persisted flags
netstat -ano | findstr :8765                # Windows port check
ollama list                                 # pulled LLM models
nvidia-smi                                  # GPU memory

12. Where to look next