MapMyCells Troubleshooting Guide

This guide aims to help researchers troubleshoot challenges they experience with MapMyCells.

Basic troubleshooting

Please ensure that your machine and web browser are up to date. MapMyCells is optimized for the latest versions of Chrome and Firefox.

Make sure that your input file meets the requirements documented at the top of our input file requirements, limits, and creation help page.


  • Input file is an h5ad file that doesn’t exceed 2 GB in size.
  • Rows should be cells and colums should be genes.
  • Genes are identified with mouse-based EnsembleIDs and listed in the index of “var” dataframe of the h5ad file.
  • Expression values are raw counts and in the “X” matrix of the h5ad file.

Documentation on how to unpack the MapMyCells .tar results file can be found at the bottom of our cell type references, algorithms, and output files help page.

Guidance of how to interpret and utilize the MapMyCells output is available via this tutorial notebook and via the additional output documentation on GitHub.

Advanced troubleshooting

If you run into an issue that’s not resolved through the above, please create a post in the MapMyCells sections of the Community Forums.

Your post should include the following information:

  • Your operating system and web browser
  • Your MapMyCells run ID - it can be found in the error message of the MapMyCells UI (see screenshot example below)
  • Information on the data you’re trying to map, e.g species, modality, formatting, etc
  • Step-by-step instructions on how to reproduce your issue