Troubleshooting

If the SDK doesn’t behave the way you expect, work through this list before opening an issue. The startup banner and the dashboard’s Requests page contain almost everything you need to diagnose problems.

`RuntimeError: egisai.init() requires api_key`

The SDK couldn’t find an API key.

Check	Fix
Is `api_key=` passed to `egisai.init()`?	Pass it explicitly.
Is `EGISAI_API_KEY` set in the environment?	Run `echo $EGISAI_API_KEY` (or check your shell rc / container env).
Is the key for the right organization?	Compare against the dashboard’s API Keys page.

Calls succeed but nothing shows up on the dashboard

Most often: the SDK is talking to a different organization than the one you’re viewing on the dashboard, or audit delivery is failing.

Check	Fix
The startup banner reports `app=…` and `policies=N`.	If `policies=0`, every call is allowed. Confirm the org you’re checking is the same one the key belongs to.
Can the process reach the control plane?	Try `curl https://app.egisai.co/healthz` from inside the same environment.
Is the audit logger backed up?	Wait a few seconds — delivery is asynchronous.

Calls succeed but no policies are enforced

Either the SDK couldn’t fetch policies at startup, or your org has none enabled.

Check	Fix
The banner says `policies=0`.	Visit the dashboard → Policies → + New policy and create one.
The banner shows a `policy fetch failed` warning.	Network issue — verify outbound HTTPS. The SDK retries on the next refresh.
Calls bypass the SDK entirely.	Confirm the integration banner (`integrations=[…]`) lists the framework you’re using.

Policies never update

When the SDK can’t establish the live update channel, it falls back to polling at refresh_interval_seconds (default 10).

Check	Fix
Network blocks long-lived HTTP connections.	Set `enable_sse=False` in `init()` to rely on polling alone.
You expected updates instantly.	Polling-only setups update on the configured interval. Lower `refresh_interval_seconds` if you need faster picks-up.

Blocked call raises unexpectedly

A PermissionError you didn’t anticipate usually means an active policy fired.

Check	Fix
Look up the call on the dashboard.	The matched policy and reason are recorded on the audit event.
Reason code is `agent_paused`.	An operator paused this Agent from the dashboard. Resume it from Dashboard → Agents to release the kill switch.
Edit or scope the policy.	Operators can target specific Agents or groups so it doesn’t apply everywhere.
Switch modes.	Set `on_block="stub"` if your code can’t tolerate exceptions. See Blocking behavior.
`semantic_guard` block during a network blip.	Set `semantic_on_outage="allow"` (the default) to fail open when the intent judge is unreachable, or leave it at `"block"` if fail-closed is your security posture.

Streaming responses look wrong

The wrapper preserves your existing for chunk in stream: loop. If chunks look truncated or duplicated, check for:

Check	Fix
You consume the same iterator twice.	Iterate once and store the result if you need to re-use it.
You mix sync and async streaming.	Use `OpenAI` with sync iterators and `AsyncOpenAI` with async iterators — don’t cross the streams.

A specific provider isn’t being governed

The integration banner lists every provider and framework whose package is patched in this process.

✓ [egisai] active — … integrations=[openai, anthropic, langgraph] policies=…

If a provider or framework you expected is missing:

Check	Fix
Is the provider SDK installed in the same Python environment?	`pip install <provider-sdk>` and restart your process.
Did you import the SDK before `egisai.init()`?	Re-order so `egisai.init()` runs first; the patches apply at init time.
Are you using an agent framework we don’t list?	Most agent frameworks delegate to OpenAI / Anthropic / Google under the hood — the direct-provider patch governs them transparently even if no framework-specific row is on the banner.
Are you calling a custom HTTP endpoint?	Use the HTTP fallback.

Sub-agent isn’t appearing on the dashboard

Check	Fix
The first call has run.	Sub-agents are registered lazily on first use.
`egisai.init()` runs before the first `set_context()`.	If `set_context()` runs first, the SDK logs a warning and skips registration.
Network can reach the control plane.	Ensure outbound HTTPS to your control plane is allowed.

Where to look next

The startup banner — confirms which integrations are active and how many policies are enabled.
The dashboard — every governed call is recorded with verdict, matched policy, latency, and tokens. Most “why did this happen?” questions are answerable from one row.
The SDK release notes — version-specific changes that may affect behavior.

If you’ve checked all of the above and the symptom persists, please reach out through the support channels listed on Support.

Get started

Core concepts

Integrations

Gateway

Coverage

Guides

Operations

Troubleshooting

`RuntimeError: egisai.init() requires api_key`

Calls succeed but nothing shows up on the dashboard

Calls succeed but no policies are enforced

Policies never update

Blocked call raises unexpectedly

Streaming responses look wrong

A specific provider isn’t being governed

Sub-agent isn’t appearing on the dashboard

Where to look next

What’s next

Configuration

Releases

​RuntimeError: egisai.init() requires api_key

​Calls succeed but nothing shows up on the dashboard

​Calls succeed but no policies are enforced

​Policies never update

​Blocked call raises unexpectedly

​Streaming responses look wrong

​A specific provider isn’t being governed

​Sub-agent isn’t appearing on the dashboard

​Where to look next

​What’s next

Configuration

Releases

`RuntimeError: egisai.init() requires api_key`

Calls succeed but nothing shows up on the dashboard

Calls succeed but no policies are enforced

Policies never update

Blocked call raises unexpectedly

Streaming responses look wrong

A specific provider isn’t being governed

Sub-agent isn’t appearing on the dashboard

Where to look next

What’s next