Troubleshooting from the failures we actually saw
A practical lookup table from the documented operating incidents.
OUR OBSERVATIONLast verified: 2026-09-27 · Build 1.9.37
Quick reference. The long path with checkpoints: chapter 11 of the guide.
Symptom → cause → fix
| Symptom | Cause | Fix |
|---|---|---|
Black frames / Camera frontend has timed out | Loose CSI ribbon | Reseat, reboot, re-run camera baseline. |
DMA wait completion timed out | One card hung | Reset card/remove-rescan; if recurring, swap card/slot. |
simplejpeg: numpy.dtype size changed | numpy ≥ 2 in runtime venv | pip install "numpy<2". |
| Labels detected instead of the card | Global colour vs lens vignetting | Local background model (1.9.33) + empty-belt reference. |
| Glare spots become parts | Single-frame empty reference | 16-frame median + noise map (1.9.35); polariser/lighting. |
| 7/25 negative photos are empty | Empty negatives poison the class | Delete; negatives are real foreign parts. |
| Footer shows old build | Service/cache stale | systemctl restart vorsa + hard reload. |
vcgencmd: ioctl_set_msg failed | Damaged SD card / VideoCore mailbox incident | New card, restore image, prove camera first. |