Troubleshooting Matrix

Use this matrix to quickly diagnose and recover from common workflow failures.

Document Control

Field	Value
Author	Geraldson Muluh
Owner	GCBM Assistant maintainers
Last reviewed	2026-03-27
Review cadence	Monthly

Simulation

| Symptom | Probable cause | Verify | Recovery | | --- | --- | | Validation fails | Missing required input path | Check inventory, AIDB, yield paths | Set missing files and re-validate | | Run starts then fails | Invalid mappings or corrupted input | Inspect first error in log panel | Correct mapping/input and run again | | No output DB | Run interrupted before completion | Check gcbm_project/output/ | Re-run after resolving errors |

Compilation

| Symptom | Probable cause | Verify | Recovery | | --- | --- | | Compile button returns failure | Source simulation output missing | Confirm source project has outputs | Re-run simulation or choose correct source | | Charts later show empty data | Wrong DB selected | Inspect DB path and expected tables | Recompile and load correct DB | | Map mode unavailable | TIFF outputs not produced | Check processed_output/spatial/ | Recompile with spatial output enabled |

Visualization

| Symptom | Probable cause | Verify | Recovery | | --- | --- | | No charts | DB not loaded or no views | Confirm load success and tables | Load correct DB and rebuild chart | | Spatial controls appear but map is blank | Invalid TIFF folder | Confirm selected folder contains TIFF files | Re-select spatial output folder | | Playback or year slider appears stale | Cached map built from old state | Change indicator and reload | Reload spatial directory to rebuild cache |

Installer and Docs CI

| Symptom | Probable cause | Verify | Recovery | | --- | --- | | Cross-repo checkout fails in installer workflow | Token scope or approval missing | Check CROSS_REPO_READ_TOKEN settings | Update token scope and org approval | | Docs workflow fails on PR | Link, anchor, or markdown rule violation | Inspect docs-quality logs | Fix broken link/anchor/style and rerun |