Handbook

Troubleshooting Forge LCDL

Symptom-first index. When in doubt, enable ParseFailure.snippet / TransportFailure text from Err payloads and grep the task under src/forge_lcdl/tasks/.

Updated 2026-07-06

Contract and registry

Symptom	Likely cause	What to try
`UnknownContractError`	Typo in `task_id` / `version`, or task not registered in `TASK_REGISTRY_V1`	Confirm spelling with `TASK_REGISTRY_V1` in `src/forge_lcdl/tasks/`
`SchemaFailure` (missing keys)	Input dict missing keys the task validates before chat	Compare payload to `contract.md` tables and `load_contract_spec(...).input_schema`
`SchemaFailure` (after model output)	Model JSON missing required top-level keys	Tighten temperature, shorten context, check `failure_modes` in `contract.json`

Parsing and gateway-shaped bodies

Symptom	Likely cause	What to try
`ParseFailure` (empty assistant content)	Gateway returned blank completion	Inspect raw transport; bump timeout; retry
`ParseFailure` (non-JSON)	Model violated JSON-only instructions	Prefer JSON mode path in `chat_with_json_mode_then_plain`; retry plain
`GatewayFailure` with `{"error": ...}` in 200 body	Upstream error encoded as JSON	Treat as upstream failure—not an LCDL parse bug

Transport and Granite

Symptom	Likely cause	What to try
`TransportFailure`	Network, TLS, DNS, `chat/completions` 4xx/5xx	`scripts/curl_chat_gateway_probe.sh`, `scripts/gateway_probe_lcdl.py`
`JSON mode` unsupported	Gateway lacks `response_format`	Library falls back to plain completion; verify in logs
Missing / wrong Granite env	Integration tests skip or fail	`FORGE_LCDL_GRANITE_ENV_FILE`, `README.md` Granite table
413 / 400 / timeouts on large prompts	Deployment limits	Reduce user payload or split chunks; `FORGE_LCDL_STRESS_CONTEXT` is informational only

RAG and citations

Symptom	Likely cause	What to try
RAG required but no retriever	`LcdlClient` policy `rag="required"` without `retriever`	Wire `Retriever` (RAG.md)
Citations guard fails	Policy expects evidence spans	Provide packs or loosen `verification` (VERIFICATION.md)

Cursor and MCP

Symptom	Likely cause	What to try
Agent opened wrong folder	Rules/skills apply per workspace root	Open repo that contains `pyproject.toml` and `src/forge_lcdl` (CURSOR-INTEGRATION.md)
MCP sidecar cannot import `forge_lcdl`	Wrong `cwd` / `PYTHONPATH`	Align with `.cursor/mcp.json.example`, reinstall `pip install -e .`
Optional MCP SDK missing	Extra not installed	`pip install 'forge-lcdl[mcp]'`
Tool calls wrong repo path	MCP `cwd`	Point `cwd` at forge-lcdl checkout root

Game tasks (`board_game_`, `game_move_`)

Symptom	Likely cause	What to try
Illegal `move_id` rejected	Model invented an ID outside engine legal set	Constrain prompts; pass full legal move list; see GAME-ENGINE.md

Doc completeness and drift

Run the contract audit (non-strict by default):

python3 scripts/audit_contract_docs.py

Use --strict locally or in CI once sidecars and headings are complete.

See also docs/KNOWN-LIMITATIONS.md, CONTRIBUTING.md.

Forge LCDL