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.
