Troubleshooting

Server will not start

Check

Action

Port in use

oneopen serve --port 9000

Wrong Python env

python -m oneopen_ml_studio version

Corrupt / missing DB

oneopen init (or point ONEOPEN_DATA_DIR at a fresh folder)

UI errors / blank pages

  • Hard-refresh the browser (static JS may be cached).

  • Confirm /static/js/app.js loads (DevTools network).

  • Check the terminal running oneopen serve for traceback.

Label Assist fails

Error / symptom

Fix

Missing ultralytics

pip install "oneopen-ml-studio[yolo]"

No annotations created

Add project classes whose names match the model’s class names

Slow first run

Ultralytics downloads weights on first use — needs network once

SAM fails

Error / symptom

Fix

Cannot import SAM

Install segment-anything + [sam] extra

Checkpoint missing

Place sam_vit_b_01ec64.pth (or l/h) in ~/.oneopen/models/

CUDA OOM

Use ViT-B, smaller image, or CPU

Training fails

Error / symptom

Fix

Missing ultralytics / libreyolo

Install the matching extra

CUDA OOM

Lower batch / imgsz, or use a smaller model / CPU

Empty labels / no detections ever

Ensure annotations exist and splits include labeled train images

DataLoader worker exited (Windows)

App forces workers=0; update to latest OneOpen ML Studio if you still see this

mAP stuck at 0.000 early

Often normal for first epochs — wait or check labels

Job stuck after restart

Training threads die with the server; start a new job

Import issues

  • Prefer YOLO layout with images/, labels/, and data.yaml.

  • Zip must contain that structure at the archive root or one top-level folder.

  • use_source_as_location only applies to folder import, not zip.

Export issues

  • Create a version first when the UI requires one.

  • COCO export is JSON-only (no image files inside the artifact).

  • VOC is not implemented — use YOLO or COCO.

Where to get help