Troubleshooting guide

Below are some common issues you might face and steps to resolve them. If you encounter something not explained below, then please open an issue: Hou-Lab-CSHL/cheese3d#issues.

Minimal Pixi version

If you setup your environment using Pixi as described in Setup, then you might encounter issues where the pixi.toml file is has errors. This is because our environment requires Pixi v0.66.0. Check your version with:

pixi --version

If this reports anything lower than v0.66.0, please install the latest version of Pixi.

Trouble launching labeling or visualization GUIs (napari)

Note

Napari GUIs require a system with a display to function correctly. Headless systems like servers cannot run the GUIs. This is an expected limitation.

Sometimes napari-based GUIs will fail to launch even on a system with a display. In particular, this can fail silently when running via cheese3d interactive. Debug this by manually launching the GUI:

cheese3d visualize [project name]

If you receive an error similar to below:

This application failed to start because it could not find or load the Qt platform plugin "xcb".

Available platform plugins are: linuxfb, minimal, offscreen, xcb.

Reinstalling the application may fix this problem. Aborted (core dumped)

This means that the graphics library underlying Napari failed to install correctly. You can try to fix this by reinstalling:

pixi reinstall

You may need to reinstall multiple times before the issue is resolved. Sometimes exiting the terminal completely and restarting helps. This should be a one time issue that does not re-occur after it has been resolved.