Troubleshooting FAQ

Troubleshooting & FAQ

Before opening an issue or a PR, please check this live troubleshooting document.

1. Docker Port 8000 Conflicts

If you encounter a failure bringing up the api service because port 8000 is already in use:

• Diagnosis: Run lsof -i :8000 (Mac/Linux) or netstat -ano | findstr :8000 (Windows) to identify the conflicting process.
• Fix: Either terminate the conflicting process, or override the port in your local .env file by changing the API bind port.

2. Postgres pgvector Extension Missing

AgentWatch requires the pgvector extension for the Postgres database.

• Diagnosis: If you see psycopg2.errors.UndefinedObject: type "vector" does not exist, you are likely running a standard Postgres image.
• Fix: Ensure you are using the official Docker compose setup which pulls the pgvector/pgvector:pg16 image. If running locally outside Docker, you must manually install the pgvector extension into your Postgres instance.

3. Agent Execution Hangs

If your subagent or CLI command appears to hang indefinitely:

• Check Redis: Ensure the Redis container is running. Celery workers require Redis to broker the background tasks.
• Check Workers: Ensure you started the worker container (docker compose up -d worker). If workers are starved, tasks will queue indefinitely.