# Troubleshooting

Common issues and how to resolve them.

### Authentication Errors

**`AuthenticationError` (401)**

The API key is invalid, expired, or does not have access to the requested project.

* Verify the key starts with `hf_sk_` and was copied in full.
* Check that the key is associated with the correct account and project.
* If you rotated the key, update it in your environment variables and restart the process.
* For self-hosted deployments, verify that `token_url` points to your auth service.

```python
# Verify the key is being read correctly
import os
key = os.environ.get("HIGHFLAME_API_KEY", "")
print(f"Key starts with: {key[:8]}...")
print(f"Key length: {len(key)}")
```

***

### Connection Errors

**`APIConnectionError` — timeout or network failure**

The SDK could not reach the Highflame service.

* For SaaS: verify outbound HTTPS (port 443) is allowed to `shield.api.highflame.ai`.
* For self-hosted: verify `base_url` and `token_url` are correct and the service is running.
* Check if a firewall or proxy is blocking the connection.
* Increase the timeout if your network has high latency:

```python
client = Highflame(api_key="hf_sk_...", timeout=60.0)
```

***

### All Requests Are Denied

**Every request returns `decision: "deny"`**

This usually means either the policies are overly broad, or the request is being evaluated with context that triggers a `forbid` rule.

1. Check which policies are determining the decision:

```python
resp = client.guard.evaluate(request)
print(resp.policy_reason)
print(resp.determining_policies)
```

2. Use `explain=True` to get the full policy trace:

```python
resp = client.guard.evaluate(GuardRequest(..., explain=True))
print(resp.explanation)
print(resp.root_causes)
```

3. Switch to `monitor` mode temporarily to let requests through while you investigate:

```python
resp = client.guard.evaluate(GuardRequest(..., mode="monitor"))
print(f"Would have been: {resp.actual_decision}")
```

4. Inspect loaded policies:

```python
policies = client.debug.policies()
for p in policies:
    print(p)
```

***

### No Policies Are Loaded

**`client.debug.policies()` returns an empty list**

Policies are scoped to your account and project. If no policies are loaded:

* Verify you are using the correct `account_id` and `project_id`.
* Check that policies have been created and published in the Highflame console.
* For self-hosted deployments, verify the Cedar policy storage is accessible.

***

### `BlockedError` Raised Unexpectedly

**A Shield decorator raises `BlockedError` when you didn't expect it**

`BlockedError` is only raised by `@shield.prompt`, `@shield.tool`, and related decorators — never by direct `client.guard.evaluate()` calls.

If this is happening in tests, switch to `mode="monitor"` for the test:

```python
@shield.prompt(mode="monitor")
def chat(message: str) -> str:
    ...
```

If it is happening in production, inspect the response:

```python
try:
    result = chat(message)
except BlockedError as e:
    print(e.response.policy_reason)
    print(e.response.determining_policies)
    print(e.response.signals)
```

***

### Session Tracking Not Working

**`resp.session_delta` is always `None`**

Session tracking requires a consistent `session_id` across turns. Verify:

* The same `session_id` is passed on every turn of the conversation.
* The `session_id` is not `None` or an empty string.

```python
# Incorrect — new ID on every call
resp = client.guard.evaluate(GuardRequest(..., session_id=str(uuid.uuid4())))

# Correct — same ID across all turns of a conversation
SESSION_ID = f"sess_{user_id}_{conversation_id}"
resp = client.guard.evaluate(GuardRequest(..., session_id=SESSION_ID))
```

***

### High Latency

**Requests are slow**

* Check `resp.latency_ms` to distinguish SDK overhead from service latency.
* Use `resp.tiers_evaluated` (with `explain=True`) to see which detector tiers ran.
* For latency-sensitive paths, consider using `detect.run()` instead of `guard.evaluate()` — detection only, no Cedar policy evaluation.
* For ZeroID: use `tokens.verify()` (local JWKS verification) instead of `tokens.session()` (introspection) when revocation checks are not required.

***

### Import Errors for Python Framework Integrations

**`ImportError: langchain is required for HighflameMiddleware`**

These packaged framework integrations are Python-only today and require extras to be installed:

```bash
pip install 'highflame[langgraph]'   # for LangGraph
pip install 'highflame[crewai]'      # for CrewAI
pip install 'highflame[strands]'     # for AWS Strands
```

***

### ZeroID Issues

For ZeroID token verification failures, delegation errors, and self-hosted deployment issues, see the [ZeroID Troubleshooting](/agent-identity-zeroid/guides/troubleshooting.md) guide.

***

### Getting More Information

* Use `debug=True` in `GuardRequest` to get raw detector results in the response.
* Use `explain=True` to get the Cedar policy trace and root causes.
* Check the observatory in [Highflame Studio](https://console.highflame.ai/) to inspect individual request traces.
* For persistent issues, open a support ticket through the console with your `request_id` from the `GuardResponse`.


---

# 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/guides/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.