Skip to content

Troubleshooting

Installation

pip install micro-sam fails. The PyPI package needs Python 3.11 or newer; check with python --version. If it still fails, install micro-SAM from conda-forge instead (pixi add micro_sam or conda install -c conda-forge micro_sam), then pip install omero-annotate-ai.

zeroc-ice fails to build with pip. Use pixi or conda, which provide ready-made builds. With plain pip, install a wheel for your platform from Glencoe Software first: Linux · Windows · macOS.

The widgets do not appear in Jupyter. Use JupyterLab 4 or Notebook 7 with ipywidgets 8 installed in the same environment (pixi add ipywidgets). Restart the kernel after installing. The Jupyter widgets do not work in marimo; use the marimo notebooks there.

Connecting

The connection widget says it cannot connect. Check the server address in OMERO.insight or with your OMERO admin. Websocket addresses (ws://…/omero-ws or wss://…) work through most firewalls; the classic port 4064 is often blocked outside the institute network.

My password is not remembered. By design. In the Jupyter connection widget you can tick the option to store it in your system keychain (a Linux server without a desktop may have none); the napari plugin never stores it.

Annotating

No napari window opens, or the kernel crashes when it should. napari needs a graphical desktop. On a remote machine, run Jupyter from inside a remote desktop session (VNC or similar), not via SSH or JupyterHub only.

The notebook cell keeps running. It waits until you close the last napari window of the batch. That is normal.

micro-SAM is very slow. Each image needs an embedding before you can click. Without a GPU this takes tens of seconds per image. Use vit_b_lm, switch on patches, and keep batches small.

An upload failed. The run carries on with the next unit; the failed one stays unannotated and its error is in the error column of the set's tracking_table.csv. Resume the set to try again.

Resuming says a unit "needs review". Its mask in your folder and its label file on OMERO differ. Delete the one that is wrong and resume again; see Pixel checks.

"N units are being annotated elsewhere (skipped)". Another computer claimed those units for its current session. They come back when that session saves or releases them, or after workflow.claim_hours (default 6) if it went quiet. Claims left by your own earlier runs on this computer never block you.

A mask ended up in annotation_output/conflicts/. Someone else saved that unit first, so yours was not uploaded. Compare the two and, if yours is better, use ts.review() on that unit.

"Not enough images" when starting. train_n + validate_n + test_n is larger than the number of images in the container (after well filtering). Lower the counts or use segment_all: true.

Config files

Loading my YAML fails with "unknown key" or RemovedConfigKey. Unknown keys are refused, so a typo never goes unnoticed; check the name against the configuration reference. Keys from 0.4 that moved name their replacement in the error, see migrating from 0.4.

Does running a training set change my YAML file? No. A loaded YAML is a template; the set keeps its own config.yaml (with sessions and progress) in its folder under ~/omero_annotate_ai/.

Still stuck?

Open an issue on GitHub with the error message, your config (without passwords) and the package version:

from importlib.metadata import version

print(version("omero-annotate-ai"))