Troubleshooting

This page covers common issues and their solutions. If your problem isn't listed here, check the logs first -- they usually point to the root cause.

Setup and startup issues

Port already in use

Error: EADDRINUSE: address already in use :::4096

Fix: Stop whatever is using the port, then try again.

# Option 1: Use the built-in stop command
make stop

# Option 2: Find and kill the process manually
lsof -i :4096
kill -9 <PID>

You can also change ports in docker/docker-compose.yml:

ports:
  - '5096:4096' # Map to a different host port

MongoDB connection failed

Error: MongoServerError: connection timed out or gateway fails to start.

Check if MongoDB is running:

docker compose -f docker/docker-compose.yml ps mongodb

Check the connection string in api/.env:

# For Docker: mongodb://localhost:27018/hyplab (port 27018)
# For local MongoDB: mongodb://localhost:27017/hyplab (port 27017)

Test the connection:

mongosh "mongodb://localhost:27018/hyplab"

Redis connection failed

Error: Redis connection failed or cache/background jobs not working.

Check if Redis is running:

docker compose -f docker/docker-compose.yml exec redis redis-cli ping
# Should return: PONG

Verify the port in api/.env:

# For Docker: redis://localhost:6380 (port 6380)
# For local Redis: redis://localhost:6379 (port 6379)

Dependencies missing

Node modules: Cannot find module 'express' or MODULE_NOT_FOUND

cd api && rm -rf node_modules package-lock.json && npm install
cd ../app && rm -rf node_modules package-lock.json && npm install

Python: ModuleNotFoundError: No module named 'fastapi'

cd agents && pip install -e .

Docker volumes: If dependencies are missing inside containers:

make clean
make setup

Frontend issues

Build errors

TypeScript errors:

cd app && npm run type-check

Missing translations:

cd app && npm run i18n:convert

Build cache issues:

cd app && rm -rf .next && npm run build

API connection errors

Symptoms: Failed to fetch, CORS errors, 404 on API calls.

Check that NEXT_PUBLIC_API_URL=http://localhost:4096 is set in app/.env.local.
Check that the API is running: curl http://localhost:4096/health
If you see CORS errors, ensure the frontend URL matches what the gateway expects.

AI agent issues

Agents not working

Symptoms: WebSocket connection failed, AI features return errors.

Check if agents are running:

ps aux | grep python

Start agents manually:

cd agents
make run-enrichment   # Port 4098
make run-templates    # Port 4100
make run-synthetic    # Port 4099
make run-persona-generator  # Port 4101

Verify your LLM API key is set in agents/.env. See LLM Setup.

Docker issues

Containers not starting

Check container logs:

docker compose -f docker/docker-compose.yml logs

Rebuild containers:

docker compose -f docker/docker-compose.yml up --build

Full clean and restart:

make clean
make dev

Volume or data issues

If data isn't persisting or node_modules is missing in containers:

docker compose -f docker/docker-compose.yml down -v
docker compose -f docker/docker-compose.yml up --build

Environment variable issues

Variables not loading

Check file locations:
- Backend: api/.env
- Frontend: app/.env.local
Verify format (no spaces around =):

PORT=4096         # Correct
PORT = 4096       # Wrong

Restart services after changing .env files:

make stop && make dev

Performance issues

Slow API responses

Check database indexes -- they are created automatically on startup. Look in gateway logs for index creation messages.
Check Redis is running and caching is working: redis-cli -p 6380 ping
If queries are slow, check MongoDB query profiling:

// In mongosh
db.setProfilingLevel(2) // Log all queries
db.system.profile.find().sort({ ts: -1 }).limit(10)
db.setProfilingLevel(0) // Disable when done

High memory usage

Check resource usage:

docker stats

Add memory limits in docker/docker-compose.yml:

services:
  gateway:
    deploy:
      resources:
        limits:
          memory: 2G

Debugging tips

View logs

# All services
make logs

# Specific service
make logs-api   # Gateway
make logs-web   # Frontend

# Or with Docker Compose
docker compose -f docker/docker-compose.yml logs -f gateway

Enable debug logging

Set LOG_LEVEL=debug in api/.env for more verbose backend logs.

Test API endpoints manually

curl http://localhost:4096/health
curl http://localhost:4096/api/v1/people?page=1&page_size=5

Debug database

# Connect to MongoDB
docker compose -f docker/docker-compose.yml exec mongodb mongosh

# Useful queries
show collections
db.people.countDocuments()
db.people.find({workspace_id: "your_ws_id"}).limit(3)

# Connect to Redis
docker compose -f docker/docker-compose.yml exec redis redis-cli

PING          # Should return PONG
KEYS *        # List all cache keys
DBSIZE        # Count of keys

Debug WebSocket

# Install wscat: npm install -g wscat
wscat -c ws://localhost:4098

Still stuck?

Check logs thoroughly -- most issues leave a clear error message.
Try make clean && make setup && make dev for a fresh start.
Open an issue on GitHub with error messages, steps to reproduce, and your environment details.

Troubleshooting

On this page