Troubleshooting

Install failures

• pip resolves an old wheel — pin: pip install "neuronscope>=0.9".
• Manylinux mismatch on old distros — upgrade pip to 23.1+ before installing.
• Corporate proxy strips wheels — use pip install --index-url against your mirror.

pip install -U pip
pip install -U neuronscope

Import errors

CUDA and drivers

• Driver older than the CUDA toolkit — upgrade the driver, not the toolkit.
• Multiple CUDA installs on LD_LIBRARY_PATH — set CUDA_HOME explicitly.
• Mismatched PyTorch build — see the wheel matrix on requirements.

Hooks that never fire

The single most common recording bug: a probe selector matches zero modules. Verify:

python -c 'import neuronscope as ns; from transformers import AutoModel; m=AutoModel.from_pretrained("distilbert-base-uncased"); r=ns.Recorder(m, probes=[ns.probes.Activations("encoder.layer.*.output")]); print(r.selected_layers())'

Filing a good bug report

Include the environment digest and a minimal reproducer.

ns doctor --json > report.json

• Attach report.json — it contains versions, seeds, and device info.
• Include the shortest script that reproduces the failure and the full traceback.
• State expected vs. observed behavior explicitly.