Troubleshooting¶

Common problems grouped by symptom. Find yours with Ctrl+F.

"engram conectó" does not respond¶

Cause: missing MCP config or DB in the wrong path.

engram --version                  # binary available
ls -la ~/.engram/engram.db        # DB exists
cat .mcp.json                     # MCP config at repo root

One DB only

Never use ENGRAM_DATA_DIR. All clients (MCP, CLI, hooks) must point to ~/.engram/engram.db. If you set it, the MCP writes to a separate DB and everything desyncs.

`init_child.sh` fails on Windows¶

Cause: you're using powershell.exe (v5.1), not pwsh (PowerShell 7+).

winget install Microsoft.PowerShell
pwsh
.\tools\init_child.ps1

If you prefer bash, use Git Bash or WSL2.

Empty submodules after clone¶

git submodule update --init --recursive
# If one fails:
git submodule update --init --force --recursive

Tests fail with `openseespy` import error¶

Cause: openseespy has no stable wheels for Python 3.13 on Windows.

# .github/workflows/ci.yml
python-version: '3.12'   # ← NOT 3.13

For local Windows development, use Python 3.12.

`pytest: command not found` after init_child¶

Cause: pytest lives in requirements-dev.txt, which is not installed automatically (it's optional).

pip install -r requirements-dev.txt
.venv/Scripts/python.exe -m pytest tests/   # Windows
.venv/bin/python -m pytest tests/           # Linux/macOS

Rate limit / 429 on OpenAlex or Semantic Scholar¶

python tools/cache_inspector.py rate-stats             # bucket state
echo "BELICO_API_EMAIL=your_email@example.com" >> .env  # 10x polite pool

See Cache and rate limiter.

Cache returning old data (stale)¶

python tools/cache_inspector.py clear --host api.openalex.org
python tools/cache_inspector.py clear --older-than 1d

`validate_submission.py` blocks with VERITAS MISMATCH¶

Cause: a [@citation] is not supported by the source (similarity < 0.4). Rule #13 violation.

python tools/find_top_sources.py --claim "bridge SHM detects damage with 95% accuracy"
# sim ≥ 0.6 → OK | 0.4-0.6 → hedging ("may", "suggests") | < 0.4 → reformulate

`validate_submission.py` blocks with "figure without metadata"¶

Cause: Rule #12. Every figure needs the HTML comment triplet (source / data / generated). Regenerate from code, never from an AI image generator:

python tools/plot_figures.py --domain structural --figure fig_04 --quartile q2

Preflight UNDERPOWERED / VIOLATIONS / INSUFFICIENT (F09)¶

The gate runs BEFORE writing (Q1 pre-registration).

UNDERPOWERED: raise N (run_torture_chamber.py --n-scenarios 64) or downgrade to Q3.
VIOLATIONS: preflight automatically switches to a non-parametric test; document the rationale in Methods.
INSUFFICIENT: run more simulations (with <3 runs/group no test is valid).

"Budget circuit broken"¶

Cause: the F06 tracker recorded Claude spend ≥ 100% of budget.

python tools/claude_budget_tracker.py --reset
python tools/claude_budget_tracker.py --init --budget-usd 10.0

Or switch the orchestrator model Opus → Sonnet (~5x cheaper).

Troubleshooting¶

"engram conectó" does not respond¶

init_child.sh fails on Windows¶

Empty submodules after clone¶

Tests fail with openseespy import error¶

pytest: command not found after init_child¶