Skip to content

Troubleshooting

This page covers common runtime issues when using VideoAnnotator via Docker Compose (recommended) or locally via uv.

Quick Checks

  1. Server reachable:
curl -sS http://localhost:18011/health
  1. Docker Compose service running (Compose workflow):
docker compose ps
docker compose logs -n 200 videoannotator

  1. API docs page:

  2. http://localhost:18011/docs

Common Issues

Cannot connect to the API (connection refused)

Compose:

docker compose up -d --build
docker compose logs -n 200 videoannotator

GPU Compose (avoid running both CPU and GPU services on the same host port):

docker compose --profile gpu up -d --build videoannotator-gpu
docker compose logs -n 200 videoannotator-gpu

Local (advanced):

uv sync
uv run videoannotator

Port 18011 already in use

Compose:

docker compose down

If something else is listening on 18011:

lsof -i :18011

Local (use a different port):

uv run videoannotator server --port 18012

401 Unauthorized (missing/invalid API key)

VideoAnnotator requires an API token by default.

Generate a token:

  • Local: uv run videoannotator generate-token
  • Compose: docker compose exec videoannotator newtoken

Use it in requests:

export API_KEY="va_api_xxx..."

curl -sS http://localhost:18011/api/v1/jobs \
    -H "X-API-Key: $API_KEY"

For local-only testing, you can run in dev mode (disables auth, allows all CORS origins):

uv run videoannotator --dev

Browser CORS errors

  • If you are using a local dev client, prefer --dev for development.
  • For non-dev mode, configure allowed origins via CORS_ORIGINS.

See the authentication and CORS docs:

More Help

For installation issues (FFmpeg, Python, GPU/CUDA, etc.), see: