Troubleshooting & Common Issues
Actionable resolution steps for scanner execution failures, Docker socket permissions, OPA compilation issues, and MCP timeouts.
1. Docker Socket Permission Denied
Symptom: docker: Got permission denied while trying to connect to the Docker daemon socket
Cause: The current user lacks membership in the docker system group.
Remediation: Add your user to the docker group and restart your terminal session:
sudo usermod -aG docker $USER && newgrp docker
2. OPA Rego Rule Compilation Error
Symptom: error: 1 error occurred: policy.rego:12: rego_unsafe_var_error: var msg is unsafe
Cause: A variable in a Rego deny[msg] rule is referenced without being assigned within the same rule body.
Remediation: Ensure all output variables are explicitly bound:
deny[msg] { input.risk > 8; msg := "Risk exceeds threshold" }
3. MCP Gateway Connection Timeout
Symptom: AI client reports: Error: MCP connection closed unexpectedly
Cause: Network proxy or firewall blocking Server-Sent Events (SSE) streaming connections.
Remediation: Ensure HTTP proxy allows chunked transfer encoding and disables response buffering for /mcp endpoints.
