Troubleshooting & System Diagnostics

When an observability run fails or telemetry collection stops unexpectedly, NeuronScope provides diagnostic subroutines to pinpoint the root cause.

System Diagnostics (`ns doctor`)

Run ns doctor to verify Python version, framework adapters, CUDA/ROCm drivers, and active accelerator hardware:

ns doctor
ns doctor --json > environment_report.json

Installation & Wheel Failures

• pip resolves legacy wheel: Upgrade pip via pip install -U pip prior to installing neuronscope.
• Missing framework extras: Ensure framework extras are specified, e.g. pip install "neuronscope[torch,llm]".

Hooks & Selector Debugging

If telemetry contains 0 recorded steps, the probe selector glob failed to match active model modules.

python -c 'import neuronscope as ns; scope=ns.Scope("test"); print(scope.selected_modules())'

CUDA, ROCm & Driver Issues

• CUDA out of memory during batching: Lower ring buffer size with buffer_mb=256 or use activation layer striding (stride=2).
• Driver mismatch: Verify CUDA runtime matching via torch.version.cuda.

Submitting Bug Reports