¶ Diagnostics
This page helps you quickly figure out where the pipeline is breaking: data, labeling, training, ONNX, or EyeAuras.
¶ Prerequisites
If Prerequisites are not green, fix those first. Local training will not start without managed Python, PyTorch, Ultralytics, and the ONNX tools.
| Symptom | What to check |
|---|---|
No space left on device |
Free up space on the project drive and in the managed Python folder or download cache. |
| CUDA is not being used | Check PyTorch runtime in Prerequisites; to force CPU mode, you can add device=cpu. |
| Installation fails | Click Check all, then Install missing; look at the error text on the component row. |
| YOLO asks to update | Update Ultralytics through the UI if YoloEase suggests an update. |
¶ Dataset
| Symptom | What to check |
|---|---|
| Training does not start | The dataset must contain at least one frame in train and one frame in valid. |
| A rare class does not learn | Add more examples of that class; it may have ended up in only one split. |
| Too many false positives | Add negative frames without boxes: menus, pauses, empty background, similar colors. |
| The model confuses classes | Check labels in the editor and add counterexamples for both classes. |
| Too many near-identical frames after importing video | Increase Frame step or choose a shorter Range. |
Train/Validation % split does not guarantee a good split by itself. Before a serious training run, make sure all important classes appear in different situations, not only in one short video segment.
¶ Labeling
| Symptom | What to fix |
|---|---|
| The model misses objects | Label more similar positive frames. |
| Bounding boxes are inaccurate | Adjust the boxes so they tightly fit the visible part of the object. |
| Auto-labeling is damaging the dataset | Do not accept suggestions blindly; remove false positives before Finish Job. |
| An object is sometimes labeled and sometimes not | Decide how to label that case and do it consistently everywhere. |
Model suggestions are not included in training until you click Accept or Accept all.
¶ Training
| Symptom | What to check |
|---|---|
data.yaml not found |
Rebuild the dataset through Trainer; check completed jobs. |
No best.pt |
YOLO did not finish training; check the progress feed and the error text. |
| ONNX export error | Make sure best.pt exists and that the model is a YOLO object detection model. |
| Not enough VRAM | Reduce Model Size, use yolo11n.pt, lower batch, or add device=cpu. |
| Windows uses too much memory | Do not increase workers unless needed; YoloEase uses workers=0 by default. |
On small datasets, metrics can be unreliable. Do not look only at mAP — also check real predictions in YoloEase and the OSD in EyeAuras.
¶ ONNX
| Symptom | What to check |
|---|---|
| The model does not load | It must be an Ultralytics YOLO export for object detection, ideally opset 17. |
| Class names are missing | Use label mapping in the editor or check the names metadata. |
| An external ONNX model does not work | The program running the model must support YOLO output parsing and NMS. |
A .pt file is selected in EyeAuras |
ML Search requires .onnx; keep .pt for training. |
¶ EyeAuras
| Symptom | What to check |
|---|---|
| It works well in YoloEase but poorly in EyeAuras | Compare the capture region, window scaling, effects, and the loaded .onnx. |
| Bounding boxes are offset | Check the capture region and effects before ML Search. |
| Clicks go to the wrong place | Enable OSD first, then Mouse Move, and only add the click action after verification. |
| The model sees objects that are too small | Add Width Min and Height Min in ML Find Class. |
If the issue only happens in a real scenario, record a short video of that exact problem through EyeAuras, add it to YoloEase, label it, and train a new generation.
See also: Trainer, YOLO ONNX and model weights, EyeAuras integration.