Skip to content
Core-X Docs

Troubleshooting

Port Already in Use

Terminal window
# Preferred: graceful stop via launcher
./launch-core-x.sh --stop


# Find what's using a port
lsof -i :8090


# Graceful kill (SIGTERM)
kill $(lsof -ti :8090)


# Last resort only — force kill (SIGKILL, no cleanup)
kill -9 $(lsof -ti :8090)

Service Not Responding

Terminal window
# Check health of all services
for port in 8085 8090 8091 8092 8093 8094 8095 8096 8083 8084; do
  status=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:$port/health 2>/dev/null || echo "000")
  echo "Port $port: $status"
done

Missing Dependencies

Terminal window
# Python deps
pip install -e "core-x/[cli]"


# Node deps (UI)
cd core-x/ui && npm install


# ffmpeg (required for audio/video pipelines)
brew install ffmpeg
ffmpeg -version

Stale Manifests / Registries

Terminal window
# Regenerate all registries from source
python scripts/generate-registries.py


# Validate ecosystem integrity
python core-x/scripts/validate-ecosystem.py


# Validate model zoo
python model-zoo/scripts/validate_registry.py

Event Bus Won’t Start

Terminal window
# Check if port 8085 is held by a zombie process
lsof -i :8085


# Graceful kill first
kill $(lsof -ti :8085)
# Last resort: kill -9 $(lsof -ti :8085)


# Start manually
python core-x/scripts/run_event_bus.py --host 127.0.0.1 --port 8085


# Check logs
cat .core-x-logs/event-bus.log

UI Won’t Connect to Services

  1. Verify gateway is up: curl http://localhost:8090/health
  2. Verify event bus is up: curl http://localhost:8085/health
  3. Check UI env config: core-x/ui/src/lib/env.ts for port assignments
  4. Check browser console for CORS or connection errors

Verification Checklist

Terminal window
# 1. Services healthy
curl -s http://localhost:8090/health && echo " ← gateway OK"
curl -s http://localhost:8085/health && echo " ← event-bus OK"


# 2. CLI works
corex --help


# 3. CLI imports clean
PYTHONPATH=core-x python -c "from core_x.cli.ui.theme import style; print('OK')"


# 4. UI builds
cd core-x/ui && npm run build


# 5. Schemas valid
python core-x/scripts/validate-ecosystem.py


# 6. Model zoo valid
python model-zoo/scripts/validate_registry.py


# 7. Registries regenerate without error
python scripts/generate-registries.py