Operations
Troubleshooting
Start with the audit log: every block carries a reason and ruleId that say why (Audit trail).
| Symptom | Likely cause | Fix |
|---|---|---|
Gateway will not start: could not reach AvertGate … to resolve policy | The dashboard address is unreachable (network, proxy, wrong base URL). | Check the address and network access. If the policy cannot be resolved the gateway deliberately does not start. |
Gateway will not start: rejected the API key or agent (HTTP …) | The API key or agent key is invalid or revoked, or the agent was deleted. | Verify the agent and keys in the dashboard; issue a new key if needed. |
A tool is always BLOCKed | unlisted_tools: deny: a tool that is not in the policy is rejected. | Add the tool to the policy under the name your server lists. Observe with --shadow first. |
Unexpected BLOCK | A constraint, the egress scan, the loop breaker or the response scan. | Read the record's ruleId (for example dlp_exfiltration, loop-breaker, ingress_prompt_injection). |
| The tool ran but the agent never saw the result | The response scan judged the result suspicious and withheld it. | Look for the "ingress scan detected …" reason in the record. See Runtime loop. |
No approval arrives, or an immediate BLOCK | SLACK_WEBHOOK_URL is set but APPROVAL_BASE_URL is not; or the 2-minute wait ran out. | Set both variables; change the wait with APPROVAL_TIMEOUT_MS. |
I changed the policy and nothing happened: policy reload failed … keeping active policy intact | The new file is invalid; the previous policy stays active. | Fix the error. For validation see Policy file. |
No events in the dashboard: telemetry failed to reach cloud or telemetry ingest returned HTTP … | No connection to the dashboard, or the key is rejected. | Check the connection and the API key. Tool calls are not affected; the local audit log keeps being written. |
| The audit chain does not verify | The log file was altered or corrupted. | Run avertgate verify; it reports the result and exits with code 1 when the chain is invalid. |
When filing a reportShare the record's
reason, ruleId and timestamp. Remove secrets from the policy file before sharing it.