Skip to main content
Bootstrap dừng với message ffmpeg not found in PATH.Nguyên nhân: chưa cài ffmpeg, hoặc đã cài nhưng PATH không cập nhật.Xử lý:
  • macOS: brew install ffmpeg → đóng terminal mở lại.
  • Windows: winget install Gyan.FFmpeg → đóng PowerShell mở lại. Hoặc add C:\ProgramData\chocolatey\bin\ vào PATH thủ công.
  • Linux: sudo apt install ffmpeg (Ubuntu/Debian) hoặc sudo dnf install ffmpeg (Fedora).
Verify: ffmpeg -version và ffprobe -version.
cat .asset_index/state.json thấy pid: null hoặc thiếu hẳn.Nguyên nhân: service install thất bại, hoặc service đã bị OS dừng.Xử lý:
  • macOS: launchctl list | grep com.video-agent — nếu không có, chạy lại .venv/bin/python -m tools.asset_index.service install.
  • Windows: schtasks /query /tn VideoAgentAssetIndex — nếu không có hoặc Status = Disabled, chạy lại service install.
  • Linux: systemctl --user status video-agent-asset-index — nếu inactive, systemctl --user start video-agent-asset-index.
Đọc log để biết lý do crash:
tail -50 .asset_index/logs/watcher.err.log
Khi chạy tools.asset_index.watcher hoặc search thấy:
apsw.ExtensionLoadingError: not authorized
Nguyên nhân: build apsw từ source bị disable extension loading.Xử lý: force reinstall với extension enabled:
.venv/bin/pip install --force-reinstall --no-binary :all: apsw
Hoặc dùng wheel có sẵn:
.venv/bin/pip install --upgrade --force-reinstall apsw
Xem thêm Cross-platform notes.
Trong PowerShell hoặc cmd, chữ Việt hiển thị ????? hoặc Ä á?.Nguyên nhân: console codepage default cp1252.Xử lý:
chcp 65001
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$env:PYTHONIOENCODING = "utf-8"
Tất cả .bat đã có chcp 65001 ở đầu — nếu vẫn vỡ, kiểm tra Windows Terminal settings → Profile → Use UTF-8 encoding.
Watcher log:
OpenAI API error: Incorrect API key provided
Gemini API error: API_KEY_INVALID
Xử lý:
  • Mở .env, kiểm tra key có dán đúng không (không có khoảng trắng đầu/cuối, không thiếu prefix sk-).
  • Test key trực tiếp: 
    .venv/bin/python -c "import os; from openai import OpenAI; print(OpenAI(api_key=os.getenv('OPENAI_API_KEY')).models.list().data[0].id)"
  • Nếu key đúng nhưng vẫn 401 → key đã expire/revoke. Tạo key mới.
  • Nếu lỗi 429 (quota) → check dashboard, top up hoặc đợi reset.
Lỗi:
apsw.CorruptError: database disk image is malformed
Nguyên nhân: máy crash giữa lúc ghi DB, hoặc xoá index.db khi watcher đang chạy.Xử lý:
  1. Stop watcher: service stop.
  2. Backup DB cũ (phòng có data quý): 
    cp .asset_index/index.db .asset_index/index.db.bak
  3. Xoá DB: 
    rm .asset_index/index.db
  4. Start watcher với scan-on-start để rebuild: 
    .venv/bin/python -m tools.asset_index.watcher --scan-on-start
DB rebuild lại từ raw_assets. Tốn LLM call lại — chấp nhận trade-off.
cat .asset_index/state.json thấy last_error non-null, hoặc query DB:
SELECT * FROM process_log WHERE status = 'failed' ORDER BY ran_at DESC LIMIT 5;
Common causes:
  • File bị corrupt (download dở, copy lỗi). Xoá + drop lại.
  • File quá lớn (Gemini limit ~2GB cho video). Cut nhỏ trước hoặc skip.
  • Format unsupported. Xem Mở rộng để add format.
  • Network flap. Watcher có retry, nhưng nếu kéo dài, restart service.
Force re-index:
.venv/bin/python -m tools.asset_index.router <path> --force
Drop file vào raw_assets/ nhưng processed_count không tăng.Nguyên nhân: filesystem không hỗ trợ inotify/FSEvents:
  • Ổ mạng (NFS, sshfs, AFP, SMB).
  • Sandbox container (Docker volume mount).
  • WSL ↔ Windows filesystem (/mnt/c/...).
Xử lý: dùng polling backend:
.venv/bin/python -m tools.asset_index.watcher --polling --scan-on-start
Nếu chạy qua service: edit launchd plist / Task Scheduler entry để thêm --polling vào ExecStart, sau đó re-install service.Trade-off: polling tốn CPU hơn FSEvents/inotify nhưng work everywhere.

​
Cần thêm trợ giúp?

Mở Issue trên GitHub

Cung cấp OS, Python version, log, state.json.

Đọc CONTRIBUTING

Cách báo bug đầy đủ context.