# Troubleshooting

### Common issues

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

***

### Verification tips

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

```json
{"action":"allow"}
```

```json
{"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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.highflame.ai/integrations/tailscale/troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.