Troubleshooting
The failures that actually happen, what causes them, and how to clear them.
Symptoms
Resetting
Everything core writes lives under core/data/:
rm -rf core/dataThis deletes the analysis — records and vectors — not just the cache. Application rows survive
in Postgres, so afterwards those videos will show as failed and re-index is the recovery.
To clear only the regenerable part, delete core/data/cache instead. That costs a re-download
and nothing else.
Environment notes
These look like things to fix and are not:
USE_TF=0is set before anything imports transformers. Without it, transformers imports TensorFlow — several seconds of startup and a wall of banners, for a backend nothing here uses.- The torchcodec warning is filtered, not fixed. Audio is decoded with PyAV and handed to pyannote in memory, so torchcodec is never used.
- PaddleOCR was tried and removed. It broke
cv2, forced a torch import order, had no GPU build for CUDA 13, and neededenable_mkldnn=Falseto run at all. EasyOCR replaced it. - Python 3.13 with torch 2.11.0+cu130 is the tested combination. Newer than most guides assume, and it works.
Verifying against a live server
Verify changes against a running server, not by reading code. Several bugs in this project — broken synthesis, stale ports, wrong media paths — only appeared over HTTP.