Troubleshooting

Common issues

Symptom	Likely cause	Resolution
No events show up in Highflame	The hook grant is not firing.	Confirm the grant uses send_hooks, confirm the event name matches your intended mode, and confirm your client traffic is routed through Aperture.
No events show up in Highflame	The hook URL points at the wrong endpoint.	Use https://cerberus.api.highflame.ai/v1/agent/events
Highflame returns auth or tenant resolution errors	The hook API key is missing, malformed, or not associated with the expected agent/project.	Regenerate the key in Highflame and update the Aperture apikey. If you use a custom relay, send it as Authorization: Bearer <key>, x-api-key, x-highflame-apikey, or x-goog-api-key.
Benign prompts are blocked	No baseline permit policy matches the request, so Cedar falls back to default deny.	Enable or restore the baseline permit policy for the tenant/project, then retry the request.
Policy appears to deny, but Aperture still allows the request	The matching Shield policy is in monitor mode.	This is expected. Monitor mode records actual_decision=deny telemetry while Highflame returns {"action":"allow"} to synchronous Aperture hooks.
Policy denies appear in Highflame but the client request was not blocked	The hook event is asynchronous, such as tool_call_entire_request or entire_request.	This is expected. Asynchronous hooks run after the provider response and cannot block or modify the request.
Aperture hook times out	Highflame is unreachable or Shield/AuthN latency exceeds the hook timeout.	Verify DNS/TLS/firewall access from the Aperture host to Highflame, keep fail_policy set to fail_open, and increase the hook timeout if needed.
Tool-call-specific events are missing	The hook is configured only for pre_request.	Add an asynchronous tool_call_entire_request hook grant and include tools, response_body, and raw_responses in send.
The same prompt appears more than once in async sessions	Some clients send the full conversation on every tool-producing request.	Highflame deduplicates repeated prompt/tool observations where possible, but async mode can still record distinct completed requests in the same session. Use the session view to inspect the timeline.

---

Verification tips

For synchronous pre_request, a successful Highflame hook response should look like one of these:

{"action":"allow"}

{"action":"block","status_code":403,"message":"<policy explanation>"}

For asynchronous hooks, Aperture ignores the response body. Highflame records and evaluates the event, but the provider request has already completed.

If you do not see expected results:

• Check Aperture hook delivery first.

• Confirm the hook event is pre_request, tool_call_entire_request, or entire_request.

• Confirm the Highflame API key resolves to the expected tenant/project.

• Confirm the relevant Shield policy is enabled and has the intended mode.

• Confirm the baseline permit policy is enabled for benign traffic.

• For tool-call visibility, confirm tools, response_body, and raw_responses are included in the async send array.