Troubleshooting¶

Problemas comunes agrupados por síntoma. Buscá el tuyo con Ctrl+F.

"engram conectó" no responde¶

Causa: MCP config ausente o DB en ruta incorrecta.

engram --version                  # binario disponible
ls -la ~/.engram/engram.db        # existe la DB
cat .mcp.json                     # MCP config en la raíz

Una sola DB

Nunca uses ENGRAM_DATA_DIR. Todos los clientes (MCP, CLI, hooks) deben apuntar a ~/.engram/engram.db. Si lo seteaste, el MCP escribe a una DB separada y todo se desincroniza.

`init_child.sh` falla en Windows¶

Causa: estás usando powershell.exe (v5.1), no pwsh (PowerShell 7+).

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

Si preferís bash, usá Git Bash o WSL2.

Submodules vacíos después de clone¶

git submodule update --init --recursive
# Si falla alguno:
git submodule update --init --force --recursive

Tests fallan con `openseespy` import error¶

Causa: openseespy no tiene wheels estables para Python 3.13 en Windows.

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

Para desarrollo local en Windows, usá Python 3.12.

`pytest: command not found` después de init_child¶

Causa: pytest vive en requirements-dev.txt, que no se instala automáticamente (es opcional).

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 en OpenAlex o Semantic Scholar¶

python tools/cache_inspector.py rate-stats          # estado del bucket
echo "BELICO_API_EMAIL=tu_email@ejemplo.com" >> .env  # polite pool 10x

Ver Cache y rate limiter.

Cache devolviendo datos viejos (stale)¶

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

`validate_submission.py` bloquea con VERITAS MISMATCH¶

Causa: una [@cita] no está respaldada por la fuente (similitud < 0.4). Violación Regla #13.

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 → reformular

`validate_submission.py` bloquea con "figure sin metadata"¶

Causa: Regla #12. Cada figura necesita el triplete de comentarios HTML (source / data / generated). Regenerá desde código, nunca desde un generador de imágenes IA:

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

Preflight UNDERPOWERED / VIOLATIONS / INSUFFICIENT (F09)¶

El gate corre ANTES de escribir (pre-registration Q1).

UNDERPOWERED: aumentá N (run_torture_chamber.py --n-scenarios 64) o downgrade a Q3.
VIOLATIONS: el preflight cambia automáticamente a test no-paramétrico; documentá el rationale en Methods.
INSUFFICIENT: correr más simulaciones (con <3 runs/grupo ningún test es válido).

"Budget circuit broken"¶

Causa: el tracker F06 registró gasto Claude ≥ 100% del budget.

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

O cambiá el modelo del orquestador Opus → Sonnet (~5x más barato).

Ver también¶

Cache y rate limiter · Pipeline · Reglas

Fuente canónica

Deriva de docs/shared/TROUBLESHOOTING.md, que cubre 25+ síntomas con detalle.