Troubleshooting

Run with logs to see what's happening:

python -m autoptz --log-level INFO

The in-app Logs panel shows the same stream; Camera Info shows the active execution provider + precision.

No detection boxes / "live-preview-only"

The detector model couldn't be loaded. The log says why. Common causes:

• First run, no network — the YOLO11 ONNX downloads on first use. Pre-fetch offline: python -m tools.fetch_models, or set AUTOPTZ_MODEL_PATH to an existing ONNX, or AUTOPTZ_MODEL_URL to a mirror.
• onnxruntime/cv2 missing — you installed requirements/ui.txt only. Run python tools/install.py --editable.

Tracking still works once a model is present; boxmot is optional (the tracker falls back to a built-in IoU tracker).

No face boxes / face enrollment does nothing

Face recognition is optional, but when enabled the Services panel should show where the InsightFace buffalo_l pack is being loaded from. If it reports a missing model path, open Engine → Models… and click Download on the "Face recognition pack" row (or, headlessly / for offline installers, run python -m tools.fetch_models).

Packaged builds bundle the pack under autoptz/models/insightface. Source/dev runs can also set INSIGHTFACE_HOME to a directory containing models/buffalo_l/*.onnx. The Model Manager can remove the pack only when it lives in the AutoPTZ app-data cache — a bundled or ~/.insightface copy is never deleted. Manual click-to-track still works without face recognition.

Running on CPU when a GPU is present

make_session logs the requested vs actual EP and any downgrade. Usual fixes:

• You have the wrong onnxruntime wheel. Only one can be installed — see Installation and reinstall the right accelerator wheel.
• NVIDIA — the CUDA EP needs CUDA 12.x + cuDNN 9.x; the TensorRT EP needs TensorRT 10.x on the machine.
• Force/inspect with AUTOPTZ_FORCE_EP=... and confirm in Camera Info.

First TensorRT launch is slow

TensorRT builds an engine on first run (can take minutes). It's cached persistently afterward — the second launch is fast. Run python tools/bench/ep_compare.py twice to confirm.

Wrong camera opens / camera names are generic (macOS)

Run python tools/install.py --editable so the PyObjC AVFoundation packages from requirements/base.txt are present. That lets cameras open by stable uniqueID instead of OpenCV's divergent index order.

Tracking is laggy or jittery

See Configuration. Quick levers while the 2.2 controller is being validated:

• Laggy follow — lower aim_smoothing, raise lead_time_s or kp.
• Jittery — raise aim_smoothing and check stale/lost target telemetry; the framing quiet zone is internal and should not become a normal tuning knob.
• CPU-bound — drop the detector tier, raise detect_interval (or leave quality_floor=auto), cap source fps.

App menu shows "Python" (macOS, source run)

Cosmetic — only the packaged .app (with CFBundleName=AutoPTZ) fixes the menu title. Build it with bash packaging/build_macos.sh.

Reset everything

Delete the app-data dir (~/Library/Application Support/AutoPTZ, %APPDATA%\AutoPTZ, or ~/.config/AutoPTZ) to clear cameras, settings, and the model cache. 2.0.0 uses a fresh config schema with no migration from older dev builds, so an incompatible old database should be removed if you hit load errors.