# Troubleshooting

### Common issues

<table><thead><tr><th width="215.2109375">Symptom</th><th width="187.48046875">Likely cause</th><th>Resolution</th></tr></thead><tbody><tr><td>No evaluations show up in Highflame</td><td>Hook grant not firing (wrong <code>events</code> value)</td><td>In Aperture, ensure your grant includes <code>events: ["tool_call_entire_request"]</code> and that your traffic actually includes tool calls.</td></tr><tr><td>No evaluations show up in Highflame</td><td>Missing required fields in <code>fields</code></td><td>Ensure your grant includes <code>user_message</code>, <code>tools</code>, <code>request_body</code>, <code>response_body</code>, and <code>raw_responses</code> so Highflame can normalize the payload.</td></tr><tr><td>No evaluations show up in Highflame</td><td>In grant json <code>hook</code> key might not be set to <code>highflame</code></td><td>Ensure that in the grant json the <code>hook</code> key refers to <code>highflame</code> hook configured in the hooks section.</td></tr><tr><td>Aperture hook times out</td><td>Highflame endpoint unreachable</td><td>Verify the <code>url</code> in your hook config is reachable from the Aperture host (TLS, firewall, DNS, load balancer settings).</td></tr><tr><td>Evaluations fail with tenant resolution / auth issues</td><td>Incorrect or malformed API key</td><td>Confirm the API key starts with <code>hf_sk-...</code> and is configured as the hook <code>apikey</code>. Highflame resolves the tenant from the <code>Authorization</code> header.</td></tr><tr><td>You only see prompt evaluations (no tool evaluations)</td><td>Tool-call events not captured</td><td>Ensure your grant is configured to send <code>tool_call_entire_request</code> and that Aperture is extracting tool calls for your selected clients/providers.</td></tr></tbody></table>

Note: Highflame normalizes each Aperture event into separate evaluations: the user prompt (`process_prompt`) and each tool call (`call_tool`). A single request with multiple tool calls can therefore produce multiple evaluations in Highflame.

***

### Verification tip

Since `POST /v1/agent/events` returns `accepted` immediately, treat it as a delivery acknowledgment. If you don’t see results, focus on Aperture hook delivery success and grant matching, then check that the payload includes tool-call context.