Troubleshooting
Install / import
Section titled “Install / import”- Use Python 3.10+.
- Prefer
pip install "kazenai-finops[openai]==1.2.6"(or[anthropic]/[providers]) so the supported provider SDK range is installed. - If versions disagree across README, PyPI, and runtime
__version__, trust the installed wheel metadata and file a docs bug.
Budget denials
Section titled “Budget denials”- Confirm
max_budget_usd(or the sharedSharedBudget) is large enough for the estimated maximum exposure of the next call, not just its typical cost. - Several clients each with
max_budget_usdhave separate caps; use oneSharedBudgetwhen they belong to one workflow. - Calls refused with
BudgetUnavailablewhile Agent FinOps is unreachable are the default (fail-closed). An admin can switch the organization to fail-open; see When Agent FinOps is unreachable. - Offline denial proof: Control demo.
- Budget still looks used after a serverless function returned: the settle was
queued in the background (1.2.4 and later) and the process was frozen before it
was sent. Call
kazenai.spine.guard.drain_settlements()before returning; see Latency.
UnknownModelError
Section titled “UnknownModelError”The model has no price in the pricing table, so its spend cannot be bounded and
the call is blocked before dispatch. Pin a priced model, add the price with
KAZENAI_PRICING_JSON, or opt in to KAZENAI_UNKNOWN_MODEL_POLICY=estimate.
See Configuration.
UnsupportedModeError
Section titled “UnsupportedModeError”The call used a surface Control does not guard, such as OpenAI Realtime, legacy
client.completions, or Anthropic beta Messages (client.beta.messages,
including LangChain ChatAnthropic(betas=...)), or a Responses request whose cost
cannot be bounded before the call: background=True, previous_response_id /
conversation / stored prompt, or a built-in tool. The exception’s
error_code names the reason. Use Chat Completions, responses.create with
function tools and input items, or client.messages.
LoopDetected
Section titled “LoopDetected”Raised only with monitor(..., loop_guard="block"). The request repeated one of
the same customer’s last requests on that client (or, with no customer ID, one of
the client’s calls without one) closely enough to look like a loop, so it was
refused before dispatch, and the run’s timeline has a finops.loop.anomaly event
with "action": "blocked". Drop loop_guard="block" to record repeats and send
them (the default), or pass loop_guard="off". On 1.2.2 and earlier, blocking was
the default: upgrade kazenai to 1.2.3 or later (1.2.5 is current). See Repeated requests.
Streaming
Section titled “Streaming”Use only the surfaces marked SUPPORTED in the supported-surface matrix. A normal stream with authoritative final usage settles exactly. Early cancellation, provider failure, or a stream without final usage remains financially pending rather than being recorded as an exact zero.
stream_cutoff_usd is an optional local guard based on output observed by the
client. It cannot see hidden reasoning or guarantee that the provider stopped
generating or billing immediately after the client closed the stream.
Broken links
Section titled “Broken links”File a documentation issue in the public
kazenai-core issue tracker
or in the affected package repository. The documentation source repository is
intentionally private; docs.kazenai.com is the canonical public surface.
