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. Agent Execution Blocked (LatticeVerdict.BLOCKED)

If your agent's execution halts unexpectedly:

• Diagnosis: Check the EventBus logs for a LatticeVerdict.BLOCKED event. The log will specify whether the block originated from the CapabilityLattice, StateLattice, or CognitiveLattice.
• Fix: If this is a false positive (e.g. the ShadowSimulator incorrectly predicted a system violation), use the InvariantEvolver API to submit the trace and suggest a threshold relaxation.

3. Asynchronous EventBus Bottlenecks

If telemetry seems delayed or is dropping during high-throughput execution:

• Diagnosis: Monitor the internal EventBus queue depth metrics.
• Fix: Ensure your background worker threads are not starved. The V2 EventBus uses non-blocking dispatch, but if your disk I/O is saturated (e.g. writing massive telemetry logs synchronously), it can slow down the worker threads. Increase worker pool size or batch writes.

4. Background Workers Hanging

If your CLI command appears to hang indefinitely waiting for a background task:

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