Skip to content

Troubleshooting (user-focused)

  • Readiness first

    If /api/ready is red, everything else will be weird.

  • Corpus sanity

    “Wrong results” are often “wrong corpus” or “index never completed”.

  • Infra reality

    Postgres/Neo4j must be reachable from the backend environment that’s running.

Quickstart UI tour Deep troubleshooting

Fast checks (do these in order)

# 1) Backend reachable?
curl -sS "http://127.0.0.1:8012/api/health" | jq .

# 2) Backend ready (DB connectivity)?
curl -sS "http://127.0.0.1:8012/api/ready" | jq .
  1. Open Dashboard → System Status
  2. Confirm Postgres + Neo4j status
  3. Confirm “Ready” is green

Symptom → likely cause → fix

Symptom Likely cause Fix
UI loads but search returns nothing Corpus not indexed (or wrong corpus) Index a corpus and wait for complete (/api/index/<corpus>/status)
/api/ready fails DB services not reachable Start Docker services (./start.sh), check Postgres/Neo4j containers
Indexing errors on a file Unsupported encoding or giant binary Exclude the file type; reindex
Search is slow Large candidate sizes, slow provider calls, graph enabled Start with /api/search, disable graph, reduce top-k; then tune

“My corpus indexed, but results look wrong”

  • Confirm you’re searching the correct corpus_id
  • Use /api/search and inspect source for top matches
  • Try disabling one leg at a time (include_graph=false, then include_sparse=false, etc.)
  • If you recently changed embedding models/dimensions, do a full reindex (force_reindex=true)
When you need the deeper page

The main troubleshooting reference covers deeper failure modes (Docker vs local backend, monitoring, and diagnosis paths). See Troubleshooting.