SimpleDet Docs

Troubleshooting

Common install, dataset, runtime, and auto-adaptation failures in the current SimpleDet repository.

Overview Quickstart Core Concepts API Reference

Use this page when the public examples are correct but your local environment or dataset wiring is not behaving as expected.

Problem	Likely cause	Fix
`python -m simpledet --check-runtime` fails	Missing or incompatible optional runtime packages	Reinstall with `python -m pip install ".[cpu]"` and verify the runtime stack together.
Backbone swap raises `ModelPatchError`	The encoder does not expose usable feature metadata, or the detector family cannot infer the expected feature levels	Prefer a supported `timm` encoder, keep `strict_auto_adapt=True`, or provide explicit `backbone_cfg` and `feature_channels`.
Pipeline training crashes before the first iteration	Missing annotation file, wrong dataset root, wrong `tif_channels_to_load`, or category count mismatch	Check `data_folder`, annotation paths, channel count, and that `categories` matches the intended class count.
Dataset format errors during exploration	Auto-detection is ambiguous or the dataset is not COCO-compatible for the pipeline path	Pass an explicit `format=` to `load_dataset()` and convert to COCO JSON before using the pipeline.
CUDA is available but the lightweight helper still runs on CPU	`device="auto"` currently resolves to CPU in the lightweight inference path	Pass `device="cuda:0"` explicitly and verify your PyTorch CUDA build separately.
`native-manifest.json` is missing after a run	The native runtime writes the manifest after a successful training or evaluation pass	Check that the output directory is writable and that the run completed without an exception.

Useful checks

python -m simpledet --check-runtime
python - <<'PY'
from simpledet._model_resolution import list_available_encoders
print(list_available_encoders(pattern="resnet*")[:10])
PY