Diagnostics: the recipe book

How to read this page #

Every recipe: symptom (what you see) → cause (why) → fix. Sources: real pilot runs, the defect register (DEFECTS.md, 43 findings) and the installer debugging journal. If a recipe is missing — open an Issue with the output of selftest and status --json.

Installation #

Symptom: install.ps1 hangs at the pip step. Cause: pipe deadlock on large output (historic installer defect D-04: stdout overflowed, the process waited for a reader). Fix: update to the refactored installer (async drain + timeouts with TimeoutScale); temporarily — pip install -e . manually in a venv.

Symptom: certificate verify failed on the first model download. Cause: corporate TLS proxy with certificate substitution; pip/python do not trust the corporate root CA. Fix: install.ps1 -WithTruststore or pip install truststore; alternative — pre-place the model into RAGRAF_MODEL_CACHE.

Symptom: the Microsoft Store python opens instead of the real one. Cause: Windows stub aliases (python3.exe in WindowsApps) intercept the command. Fix: the refactored installer detects the stub and says so directly; manually — disable the aliases (Settings → App execution aliases) or pass the full interpreter path.

Indexing #

Symptom: ensure reindexes everything every run. Cause: files change mtime/content between runs (generated code, line-ending normalization, antivirus quarantine) — corpus_hash diverges. Fix: status --json → compare corpus_hash before/after; exclude generated directories via exclude; check that .ragraf/ is not inside include.

Symptom: indexing a large corpus (hundreds of files) is slow. Cause: the AST walk is sequential (the documented "8 cores parallel" goal is not implemented yet — R-PERF-1); embeddings run on CPU. Fix: narrow include; move embeddings to a GPU (see gpu-compute); disable CPG (joern_enabled: false) if slice is not needed: on the pilot CPG is 64 s of 71.

Symptom: write_check does not know a table that definitely exists. Cause: the table is created outside migrations/*.sql — dynamically or in another directory. Fix: widen the schema.migrations glob in the config; check schema --table X and coverage (source conflicts are recorded there).

Joern / CPG #

Symptom: slice answers with exit code 3. Cause: capability=degraded — Joern/JDK not installed or the CPG stage failed. Fix: this is an honest refusal, not a bug: install-joern.ps1 -Download (verifies SHA-256); on large corpora — RAGRAF_JOERN_HEAP_GB; port 9500 must be free (the server starts/stops automatically).

Symptom: Joern starts but the CPG is empty. Cause: php2cpg did not support the corpus dialect/constructs; errors are in the stage log (index_status). Fix: check coverage and the log; a partial CPG is better than none — slice works over covered files, capability tells the truth.

Embeddings and search #

Symptom: search answers in a second or more. Cause: the query embedding on CPU dominates; there is no query cache (R-PERF-3). Fix: for navigation use symbol/callers (0.5–0.7 ms); keep search for semantic queries; a GPU accelerates batch indexing but barely changes single-query latency (~15 s one-time map preparation on GPU).

Symptom: vector norms in the panel show zeros/outliers. Cause: broken chunks (parse truncation) or a dim mismatch. Fix: reindex; verify embedding.dim against the model; quality lives in the panel's Quality tab (pilot norms: 0.0576–0.6627).

MCP and agents #

Symptom: the agent does not see the ragraf_* tools. Cause: the server failed to start (wrong path/interpreter in the MCP config) or the substring name filter false-positived (defect C-02). Fix: run the server command by hand — stderr shows the reason; use exact tool names in the agent config; --agent-kind external for third-party clients.

Symptom: the agent answers "from memory", ignoring the index. Cause: the regimen is not attached. Fix: usage_stats: a healthy profile is symbol/search-dominated with zero whole-file reads; add the AGENTS.md regimen to the agent's context.

Panel #

Symptom: the panel does not open, port busy. Cause: a previous instance was not stopped. Fix: the server reports the cause (8777 occupied) explicitly; stop the process or change the port (launch argument).

Symptom: settings do not save. Cause: mutations require the token (printed to the startup console); the full > fast validation rejected the values. Fix: take the token from the console/RAGRAF_ADMIN_TOKEN; check the thresholds — the server validates more strictly than the form.

Windows specifics #

• Glob case-sensitivity: **/*.PHP does not match file.php on Windows (defect E-01) — use lowercase extensions in the config; the fix is on the roadmap.
• Paths: forward slash / in the config; backslash works but / is canonical.
• Long paths (>260): enable LongPathsEnabled or keep the corpus closer to the root.
• PowerShell 5.1: unverified; use pwsh 7.6+.

Related: CLI reference → · configuration → · benchmarks and limits →