Copyright © 2026 Saccadic LLC · Patent pending.

Browse chapters
  1. Release NotesChanges by version
  2. Chapter 1What IRIS Is and Is Not
  3. Chapter 2The IRIS Data Model
  4. Chapter 3How IRIS Measures
  5. Chapter 4Safe Interpretation and the First 15 Minutes
  6. Chapter 5Dashboard Overview
  7. Chapter 6Installation
  8. Chapter 7Configuration
  9. Chapter 8Build the Model Spec and Probe Set
  10. Chapter 9Minimal Tracker Integration
  11. Chapter 10Launch the Bench and Verify Capture
  12. Chapter 11Runtime Control, Signals, Metrics, and Logs
  13. Chapter 12Integration Patterns by Model Family
  14. Chapter 13Distributed Training
  15. Chapter 14Artifacts, Reports, Export, and Security
  16. Chapter 15Troubleshooting
  17. Chapter 16Whole Model and Layer Structure
  18. Chapter 17Domain Training and Affinity
  19. Chapter 18Attention-Head Diagnostics
  20. Chapter 19MoE Expert and Router Diagnostics
  21. Chapter 20Facets and Emergent Pathways
  22. Chapter 21Gradient Residuals, Stability, Curvature, and Update Efficiency
  23. Chapter 22Adaptive Cadence and Event Detection
  24. Chapter 23CLI Reference
  25. Chapter 24Configuration-Key Reference
  26. Chapter 25API Reference
  27. Chapter 26File and Schema Reference
  28. Chapter 27Glossary and Concept Index
  29. Chapter 28The Flow Map
  30. Appendix ADiagnostic Availability Matrix
  31. Appendix BLLM Prompt Library
On this page

Chapter 15 — Troubleshooting

Installation and startup

No module named 'iris' or iris is not found. Activate the environment used for installation and training. Install into that interpreter using the distribution's instructions, then check iris --help and the smoke test.

[IRIS] NO BUNDLE CAN BE WRITTEN or an empty bundle. Read the startup line: it names the failing component and the repair. An incomplete install, an import failure, and a damaged dependency require different remedies. Follow that named repair and rerun; do not assume successful training recovered diagnostic frames that were never written.

NO SCIENCE HAS BEEN CAPTURED IN THIS RUN. This summarizes failed capture attempts, not a single diagnosis. Read the per-attempt reasons in iris.log, including startup messages. Check licensing readiness, writing, and available resources. A dryrun intentionally records no science.

Empty charts mean different things

Message or state What to do
Reading the bundle Allow the read to finish before deciding a channel is absent.
Calculating, with frame counts advancing The run contains data and analysis is progressing.
Channel not emitted Check the capture and integration requirements in Explain.
Not applicable The comparison or model structure required by the view does not exist on this run.
Declared shed or skipped Read the stated resource or coverage reason; do not replace it with zero.
Stalled analysis or a restart suggestion Review iris-bench.log; use the Bench restart control or stop/relaunch the Bench when appropriate.

Restarting the Bench reloads its frontend and analysis; it does not restart the training job. If a failure recurs, preserve the run identity and logs needed to reproduce it. Review those files before sharing them externally.

Missing or misleading metrics

No loss or held-out accuracy curve: wire the corresponding trainer reporting call. Probe outcomes are not automatically a replacement for held-out evaluation. An absent reported value is not a zero.

No answer-span accuracy: declare the expected answer or answer mask. Whole-sequence token accuracy measures something else. Check tokenization and answer endings as described in Chapter 8.

Commands have not taken effect: ensure the run directory is correct and training is reaching should_extract or extract. Read the log for the applied command and any refusal.

Unexpected differences across runs: compare model versions, probe sets, steps, definitions, cadence, resource modes, and hardware. Do not infer a learning event from a chart difference before checking those conditions.