Skip to main content

Troubleshooting

Use this page when Lore commands succeed syntactically but outputs are missing, stale, or low quality.

Quick Triage Flow​

flowchart TD
  A[Issue observed] --> B{Where is the failure?}
  B -->|Ingest| C[Check source path or URL and rerun ingest]
  B -->|Compile| D[Check lock, logs, and raw entries]
  B -->|Search or Query| E[Rebuild index and validate wiki graph]
  B -->|Settings/Secrets| F[Check settings scope and keychain/env fallback]
  C --> G[Run lore lint]
  D --> G
  E --> G
  F --> G

Common Issues​

SymptomLikely causeWhat to do
Another compile is already running.lore/compile.lock is held by a live processWait and rerun compile. If process died, rerun compile and Lore will reclaim stale lock
Compiled 0 articles unexpectedlyNo extracted content changed and hash-based incremental compile skipped workUse lore compile --force to reprocess all valid raw entries
Search results are stale or emptyIndex drift or missing manifest entriesRun lore index --repair, then retry search/query
Query answer is low-signalRetrieval context is weak or ambiguousRun lore lint, inspect gaps/orphans, improve linking, then recompile
No QA file created from query--no-file-back was usedOmit --no-file-back or check .lore/wiki/derived/qa/
Angela fails after installGit history is too shallow or no diff between last two commitsEnsure at least two commits and rerun lore angela run manually
Export fails on pdfPuppeteer/browser dependency issueReinstall dependencies and retry lore export pdf

Recovery Playbooks​

Compile appears stuck​

# 1) inspect active lore processes
ps aux | grep lore

# 2) retry compile
lore compile

# 3) if still blocked, run a full maintenance pass
lore index --repair
lore lint

Search or query quality regressed​

# 1) refresh index and manifest consistency
lore index --repair

# 2) check graph health
lore lint --json

# 3) ask a focused question again
lore query "How does compile locking work?" --normalize-question

Export artifact missing expected content​

# 1) ensure fresh wiki material exists
lore compile --force

# 2) export again in the target format
lore export bundle --out ./dist

# 3) inspect output quickly
wc -l ./dist/bundle.md

Log-Driven Debugging​

lore ingest, lore compile, and lore query produce JSONL logs in .lore/logs/.

Use these when a command fails without enough terminal detail:

# newest logs first
ls -lt .lore/logs | head

# inspect one run log
cat .lore/logs/<run-id>.jsonl

Escalation Checklist​

Before opening an issue or asking for help, collect:

  1. Command and flags used
  2. Whether --json output was captured
  3. Relevant .lore/logs/<run-id>.jsonl snippet
  4. Output of lore lint --json
  5. Whether lore index --repair changed behavior