Troubleshooting

Common Issues

Router Not Starting

Symptom: Router fails to start or port 5001 is already in use.

# Check what's using port 5001
lsof -i :5001

# Kill existing process
kill $(lsof -t -i :5001)

# Start router manually (machine-portable)
cd {PLATFORM_DIR}
conda run -n voicememo-py314 python router/server.py

Ngrok Session Error

Symptom: “Your account is limited to 1 simultaneous ngrok agent session”

# Kill all ngrok processes
killall ngrok

# Wait a moment for session to clear
sleep 5

# Start ngrok again
ngrok start main

Backend Service Unavailable

Symptom: Router returns 502 Bad Gateway

  1. Check if the backend service is running:

    lsof -i :[PORT]

  2. Test the backend directly:

    curl http://localhost:[PORT]/

  3. Check backend logs

Mixed Content Blocked

Symptom: Browser blocks content with “Mixed Content” error

This occurs when IONOS frame (HTTPS) tries to load HTTP content.

Solution: Ensure ngrok URL uses HTTPS: - Correct: https://lettre.ngrok.dev/path/ - Wrong: http://...myfritz.net:PORT

Path Not Found

Symptom: 404 or wrong service responds

  1. Check route is in config:

    cat {PLATFORM_DIR}/config/routes.yaml

  2. Restart router after config changes

  3. Test routing:

    curl http://localhost:5001/health
curl http://localhost:5001/[path]/

Checking Service Status

All Services

# Check all relevant ports
for port in 5001 5050 5100 5101 8080; do
    echo "Port $port:"
    lsof -i :$port | grep LISTEN || echo "  Not running"
done

Ngrok Tunnel

# Check ngrok status
curl -s http://localhost:4040/api/tunnels | python3 -m json.tool

LaunchAgents

# List loaded agents
launchctl list | grep -E "ai-platform|inqua"

# Check agent status
launchctl print gui/$(id -u)/com.ai-platform.router

Logs

Service Log Location
Router {PLATFORM_DIR}/logs/router_*.log
Docs {PLATFORM_DIR}/logs/docs_*.log

Restart All Services

# Stop all
launchctl unload ~/Library/LaunchAgents/com.ai-platform.router.plist
launchctl unload ~/Library/LaunchAgents/com.ai-platform.docs.plist

# Start all (in order)
launchctl load ~/Library/LaunchAgents/com.ai-platform.router.plist
launchctl load ~/Library/LaunchAgents/com.ai-platform.docs.plist