Troubleshooting

Troubleshooting guide for Highflame — authentication errors, connection errors, all-deny scenarios, session tracking, ZeroID token verification failures, and self-hosted issues.

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.

# 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:

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:

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

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

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

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

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

1. Inspect loaded policies:

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:

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

If it is happening in production, inspect the response:

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.

# 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:

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 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 to inspect individual request traces.

• For persistent issues, open a support ticket through the console with your request_id from the GuardResponse.