# Troubleshooting
| Import from an older example is missing | Check the exact alpha version and [release migration](RELEASES.md); do not invent compatibility aliases. |
| Model type missing from the basic prelude | Import the independent models prelude or its domain root. |
| Matrix/vector operation rejects a shape | Check constructor argument order, vector-list shape, and inner dimensions; `multiply` and `matmul` differ. |
| Builder cannot finish | Initialize every dense logical element; sparse unwritten coordinates are implicit zeros. |
| Sparse operation consumes unexpected memory | Check logical traversal and result occupancy; sparse storage is not a universal complexity guarantee. |
| A random method is rejected | Use a method supported by that component; indexed operations require their indexed contract. |
| Replay changes despite a fixed seed | Check method/version, stream indices, call order, counters, and floating reduction rules. |
| Simulation accelerates unexpectedly | Clear acceleration at each step before accumulating all current force contributions. |
| Mass-dependent operation rejects state | Keep mass/inverse mass consistent with `set_mass` and review selected-particle requirements. |
| Neighbor query is stale | Rebuild after position changes; wrapping coordinates does not provide periodic minimum-image distances. |
| More threads do not help | Check the active pool, PiP cap, workload size, allocations, and memory bandwidth using release builds. |
| NumPy readback rejects a file | Use a supported PiP document, correct schema, and valid scalar values; this helper does not read Workflow recording directories. |
| Python test suite skips NumPy tests | Install NumPy in the interpreter actually running the tests; a skipped suite is not interoperability evidence. |
[Guide index](README.md) ยท [Required AI instructions](AGENTS.md).