Troubleshooting

The online GUI is unresponsive

Reloading the page should fix most issues. If you have a slow network connection, consider installing PixelMap locally.

SpikeGLX ignores my .imro file

Make sure the probe part number is correct. The part number is the first number in the first tuple of the IMRO table (if using SpikeGLX release 20260115 or earlier, it will be the SpikeGLX probe type, not the part number, see below. If so, tick PixelMap’s “Legacy IMRO format” checkbox before downloading your IMRO file).

To find your probe’s part number, check either:

  • The default .imro file generated by SpikeGLX — save it from the IM-Setup tab.

  • The ~imroTbl field in a .meta file saved alongside a previous recording (usually the last field in the file).

Warning

SpikeGLX’s probe visualizer (the probe-shaped heatmap display) displays IMEC probe part numbers. ‘Probe types’ are identifiers used internally by SpikeGLX, while probe part numbers are used by IMEC - see SpikeGLX’s IMRO table documentation. As of version 2026-01-15, SpikeGLX began writing IMEC part numbers into imro headers: SpikeGLX 20260115 and later (and CatGT 5.3 and later) can read either the probe type or part number. Prior to that, the imro header used the probe types exclusively. In practice, plug your probe into SpikeGLX and verify the header value from the default .imro or .meta file generated for your probe.

SpikeGLX IMRO editing options are greyed out

This is expected behavior for non-canonical IMRO tables. SpikeGLX disables its built-in editing for imported tables that don’t match its canonical format (whole/half-shank width boxes enclosing all AP channels). This allows SpikeGLX to use external tables “as is” without risking modification.

To make further edits:

  1. Open the PixelMap GUI (or launch it locally).

  2. Upload your .imro file as a starting point.

  3. Make your modifications.

  4. Download the updated .imro file.

  5. Re-import into SpikeGLX.

The GUI crashes or shows errors on startup

  1. Make sure you are using Python 3.10 or later.

  2. Try reinstalling dependencies:

    uv sync --reinstall

  3. If using pip, ensure you’re in a clean virtual environment:

    conda create -n pixelmap python=3.12
conda activate pixelmap
pip install .

Still stuck?

Open an issue on GitHub with:

  • Your operating system and Python version

  • The full error message or traceback

  • Steps to reproduce the problem