Skip to content

jaz.exceptions

New to JAZ? This is generated API reference. Start with the docs and the concepts overview.

Public API of the jaz.exceptions submodule (import from jaz.exceptions, e.g. from jaz.exceptions import ...).

Every error defined here derives from JazException, which derives from Exception, so except JazException around jaz.invoke catches any of them. The module also publishes one warning category, UnknownRequestParamWarning, which is a UserWarning rather than an error.

Configuring JAZ is not agent execution and does not go through this taxonomy: calling a setup function wrongly raises the builtin that fits (ValueError, TypeError), and a component validating input with someone else’s library raises that library’s error — registering a template loader surfaces jinja2.TemplateSyntaxError. Each such function documents what it raises.

Bases: Exception

Base exception class for JAZ-related errors.

Bases: JazException

Class of exceptions that cause invoke to error out instead of being shown to the agent as recoverable feedback; exempt from being caught by agent-written except clauses.

An ordinary exception in REPL code is caught and shown to the agent as recoverable feedback (a Continue) so it can retry. A FatalError instead ends the REPL session and causes the invoke to error out with that error. If this invoke is a subinvoke of a parent invoke and the FatalError occurs in the REPL of that parent invoke, then that parent invoke also errors out. Thus, usually, the entire invoke tree fails and the top-level invoke raises the FatalError.

Raise FatalError when a fatal error occurs that the invoke tree cannot recover from. For example, write raise FatalError() inside a tool definition in paths that should take down the entire invoke tree. Errors from third-party libraries that you’d like to convert to a fatal error should be caught and re-raised as FatalError. A hook that would like to take down the entire invoke tree should emit an Abort(error=FatalError(...)) effect. (Emitting Abort(error=exc) where exc is not a FatalError aborts the in-progress invoke but does not propagate to the parent invoke.)

Who can decline a fatal error, since that is the whole point of the class:

Agent REPL code No — a FatalError is exempt from being caught by agent-written except and except* clauses. Two known exceptions, both under “Known limitations”.
User code Yes, by catching it — a tool or the caller is host code, and one that catches its own fatal error has decided not to fail.
A hook No — a fatal exception propagates during unwind, and no transform boundary fires on the unwind path, so there is no effect a hook could return to convert it back into normal control flow.

The purpose of this class is routing, i.e. who the error is addressed to. An ordinary error is addressed to the agent; a fatal error is addressed to the caller: “this failure is not something the agent can fix by retrying.”

It is an Exception (through JazException), not a BaseException like KeyboardInterrupt, because the caller is its audience: except Exception around invoke catches it, as it catches every other error JAZ raises. The agent’s own except Exception does not, as the table above says; that is the REPL’s doing, not the base class’s.

  • A suppressing context manager still swallows it, in the default configuration and with no imports:

    class S:
    def __enter__(self): return self
    def __exit__(self, *a): return True # truthy -> suppresses anything
    with S():
    tool_that_raises_fatal() # fatal error swallowed; the run continues

    A known limitation, not a boundary.

  • A group-wrapped fatal error is catchable. An ExceptionGroup containing a FatalError is really an ExceptionGroup, so both except Exception and except ExceptionGroup catch it. Such a group is still exempt from except*, which surfaces the FatalError leaf. A group that goes uncaught still takes down the invoke tree.

Bases: UserWarning

Emitted when a backend construction kwarg looks like a misspelled request parameter.

A backend (e.g. jaz.llm.LiteLLM) forwards any keyword it does not name as a per-request default onto the wire, so a typo like temperatrue=0.7 is otherwise sent verbatim and silently ignored by the provider. When an unrecognized kwarg closely matches a known request parameter, this warns with the suggested spelling — but the kwarg is still forwarded, since arbitrary provider-specific extras are supported by design.

Filter it like any warning category:

import warnings, jaz
warnings.simplefilter("ignore", jaz.exceptions.UnknownRequestParamWarning)
warnings.simplefilter("error", jaz.exceptions.UnknownRequestParamWarning)

Bases: TypeError, JazException

Raised when the agent’s returned value doesn’t satisfy the declared return type.

Produced by jaz.hooks.ReturnType: a mismatched return is downgraded to a Continue carrying this error, so the agent is told what it got wrong and can retry. Past ReturnType’s max_failures it is raised out of the invoke instead, with the offending value in the message. (jaz.hooks.ValidateReturn shows the agent its validator’s own exception instead.)

Bases: PermissionError, JazException

Raised when the REPL refuses a file operation its policy does not allow.

A PermissionError, so agent code handling a denied open the usual way (except PermissionError or except OSError) handles this one too, as it would outside the sandbox. What refuses it is the REPL’s own policy, not the operating system — usually allowed_read_paths / allowed_write_paths, and the message then names the offending path and the allowed patterns; errno is None. Opening a raw file descriptor is refused outright instead, with no path to report, since there is nothing to check an allow-list against.

Bases: JazException

Raised when a budget-enforcing hook stops the run because its budget is spent.

The base of two distinct causes — catch this to handle either, or the subclass to tell them apart: IterationLimitExhaustedError (the turn cap) and BudgetPoolExhaustedError (a cost/calls pool). The distinction matters to a caller that can do something different about each — e.g. offer more turns for the former but not the latter, which more turns cannot refill.

Bases: BudgetExhaustedError

Raised by jaz.hooks.IterationLimit when the per-invoke turn cap is reached.

A subclass of BudgetExhaustedError, so except BudgetExhaustedError still matches; catch this specifically to react to the turn cap alone (granting more turns can let the run finish, unlike a spent cost/calls pool).

Bases: BudgetExhaustedError

Raised by jaz.hooks.BudgetPool when its pooled cost or calls ceiling is reached.

A subclass of BudgetExhaustedError, so except BudgetExhaustedError still matches; catch this specifically to distinguish a spent cost/calls pool from the turn cap (IterationLimitExhaustedError) — more turns cannot refill a pool.

Bases: JazException

Raised when a jaz.invoke exceeds an invoke recursion limit set by jaz.hooks.RecursionLimit.

Bases: JazException

Raised when an invoke input cannot be rendered into the agent’s prompt.

Wraps whatever rendering the value raised – its own __str__/__repr__ failing, or anything else – and names the input; the original is chained as __cause__. Rendering happens before the invoke makes a single LLM call, so nothing has been spent.

It is never fatal: in a sub-invoke it reaches the parent agent as recoverable feedback, so the parent can call again without the input. One case it cannot recover from on its own: a value inherited from an enclosing jaz.scope is not the parent’s to remove, so every sub-invoke under that scope fails the same way until the scope changes. KeyboardInterrupt and other non-Exception signals are not wrapped and still end the run.

Bases: JazException

Raised when the jaz.hooks.BudgetForcing hook blocks an early return/raise finish.

Bases: JazException

Raised when an added name conflicts with a binding that already exists.

Two effects adding the same name with different values, an AddInputs key that collides with a caller’s own input or scope entry, or an AddToNamespace name already bound in the REPL namespace. Identical values coalesce instead of raising.

Bases: ValueError, JazException

Raised when the code’s leading # timeout: comment names no positive number of seconds.

An agent sets a per-execution wall-clock bound with a # timeout: <seconds> comment among the lines opening its REPL code. The value must parse as a positive, finite number, so # timeout: 120s and # timeout: 0 are rejected; a trailing # comment after the number is allowed. The offending code is not executed — the agent sees the error as ordinary REPL feedback and can correct it on the next iteration.

Bases: ValueError, JazException

Raised when an invoke input, or a namespace or input edit, names a key the REPL refuses to let it bind or drop.

Today that is __builtins__, which holds the REPL compiler’s allow-lists (which builtins, imports and attributes the agent’s code may reach), so binding or dropping it would reopen them. The framework refuses it, rather than skipping it, wherever it binds or drops a name for a caller or a hook: an input passed to invoke or scope, or an Add/Drop effect, for example. The REPL also raises it at the end of an exec whose code replaced __builtins__ (through globals(), which the compiler cannot refuse), and on every later read of the sandbox; that invoke then fails with it, and a parent invoke sees the failure as ordinary feedback. The message names the key.

Bases: JazException

Raised when a hook returns an effect at an event that does not accept it.

Every event documents the effects valid at its stage (supplies at *Send, transforms at *Complete, Abort at every control event, the *Exit events accept none). An out-of-stage effect is a hook bug — emitting it can only mean the hook expects an influence the stage cannot deliver — so composition rejects it loudly rather than ignoring it. The message names the offending effect kind and the event.

Bases: JazException

Raised when hooks compose conflicting LLM-response values for the same query.

Two cases, both order-independence violations: two distinct SupplyLLMResponse effects supplying a response at LLMQuerySend, or two ModifyLLMResponse effects setting the same field to different values at LLMQueryComplete. Identical values coalesce; distinct ones raise, because resolving by arrival order would make composition depend on hook registration or with-nesting order.

Bases: JazException

Raised when effects carrying distinct Return values fold at one boundary.

Applies wherever results fold — SupplyExecResult at REPLExecSend, ModifyExecResult at REPLExecComplete, and ModifyInvokeResult at InvokeComplete. Carried Continue results merge (outputs concatenate, exceptions group) and identical return values coalesce, but two different return values cannot be combined without picking a winner by hook order.

Bases: JazException

Raised while assembling a per-invoke blackboard’s generation 0.

Two hooks seeding the same key with different values: the board cannot pick one without depending on hook order. Surfaces before InvokeEnter is dispatched.

Bases: JazException

Raised when two BlackboardWrite effects in one event write the same key with different values.

Identical writes coalesce; distinct ones raise, since within an event the write order across hooks is irrelevant by design and has no order-independent resolution. Writes in different events are fine — the later generation overwrites.

Bases: JazException

Raised when one Hook instance is activated by more than one path at a time.

A hook instance is active via exactly one path: the propagating with MyHook():, or a single positional argument to one invoke. Overlapping them (with h: jaz.invoke(h, ...)), listing it twice (jaz.invoke(h, h, ...)), or re-entering it while active would run its setup()/teardown() more than once and clobber whatever it acquired.

Bases: JazException

Raised when a cost_budget is set but no per-call cost is available to enforce it.

The usual cause is a model the backend cannot price — LiteLLM has no entry for it, or the backend does not set LLMResponse.cost_usd at all. Use calls_budget, which counts LLM calls and needs no rates. Custom or self-hosted models reached through a base_url are rarely priced, so calls_budget is the way to cap them. Nothing is spent before this is raised, unless the backend’s model_info.can_report_cost (see jaz.llm.ModelInfo) promised a cost that a call then came back without: jaz.llm.GitHubCopilotLLM does when GitHub leaves a call’s credit figure out, and a custom backend can.

Bases: JazException

Raised when one ConfigOverride instance is entered while already active.

An instance is active within exactly one live scope at a time. Re-entering the same one — nested on a thread or concurrently from another — is forbidden, mirroring HookActivationError. Distinct instances nest freely and sequential reuse is fine; only overlapping reuse of one instance trips the guard.

Bases: IndexError, JazException

Raised when an InsertCode / DeleteCode character offset is out of range.

The character-offset twin of MessageEditIndexError: offsets follow list semantics against the code the hook saw on REPLExecEnter (a negative offset counts from the end; end-of-string is offset == len). Anything outside [-len, len] — or a DeleteCode whose resolved start exceeds its end — raises rather than being ignored or clamped, since every offset is computed against that exact snapshot and so an out-of-range one is a hook bug.

Both an IndexError and a JazException, mirroring MessageEditIndexError.

Bases: IndexError, JazException

Raised when a DropMessages / AddMessages index is out of range.

Indices follow list semantics against the snapshot the hook saw on LLMQueryEnter: a negative index counts from the end, and append is index == len. Anything outside [-len, len] for an add or [-len, len-1] for a drop raises rather than being ignored or clamped.

Both an IndexError and a JazException, so except IndexError catches it as the out-of-range failure it is, while except JazException still catches everything JAZ raises.

Bases: KeyError, JazException

Raised when a DropFromNamespace / DropInputs names a target that isn’t present.

As with Python’s del, a builtin the sandbox allows (len) that no variable shadows is not present: it is the sandbox’s policy, not a variable. Dropping a name that isn’t there is a hook bug — a typo, or a re-drop-every-turn pattern that should be first-turn-only — so it fails loud instead of no-op’ing. Set allow_missing=True for a deliberately defensive drop.

Bases: JazException

Base class for the provider/transport errors raised around an LLM call.

Catch it to handle any provider failure without naming each subclass. Each subclass documents whether it is retryable.

The names follow the openai and anthropic SDKs where they define the error (BadRequestError, APITimeoutError, APIConnectionError, …), LiteLLM’s where only LiteLLM does (ContextWindowExceededError, …), and otherwise another framework’s (ServerError, google-genai’s) or JAZ’s own (QuotaExceededError). Unlike those SDKs’ APIError, which every API error subclasses, the root here is LLMError.

Every attribute but message is None when the backend did not see it: no response came back (a timeout, a refused connection), or the backend does not expose it.

Attributes

  • message — The error message, the provider’s where it gave one.
  • status_code — The HTTP status the provider answered with.
  • body — The provider’s response body, decoded from JSON where it is JSON, else its text: its error body, or on jaz.llm.SGLangLLM a 200 it could not use or whose request was aborted.
  • headers — The provider’s response headers, with lowercase names.
  • code — The provider’s machine-readable error code, such as "credit_balance_exhausted" or "rate_limit_error": the first string among the error object’s code, type and status fields (OpenRouter’s metadata.error_type after them), else Bedrock’s x-amzn-ErrorType header; on jaz.llm.GitHubCopilotLLM, the Copilot runtime’s error code.
  • request_id — The provider’s request id (the x-request-id, request-id or x-amzn-RequestId header; on jaz.llm.GitHubCopilotLLM, GitHub’s x-github-request-id, else the Copilot service’s), to quote when reporting a problem to the provider.
  • retry_after — How long the provider asked the caller to wait before retrying, in seconds, from its retry-after-ms or retry-after header, else the retryDelay Gemini and Vertex put in the body. A value that is not a finite, non-negative number is stored as None. A backend’s retry waits this long plus jitter; a zero waits the usual backoff, and one longer than RetryPolicy.retry_after_max stops the retries.
  • is_retryable — Whether to retry it whatever its class, as the provider said in an x-should-retry header (read by jaz.llm.LiteLLM and jaz.llm.SGLangLLM; jaz.llm.GitHubCopilotLLM’s runtime passes no response headers); None leaves it to the class, and only True or False is stored. Retry caps still apply, a retry_after longer than RetryPolicy.retry_after_max stops the retries even when it is True.
__init__(message: str, status_code: int | None = None, *, body: Any = None, headers: Mapping[str, str] | None = None, code: str | None = None, request_id: str | None = None, retry_after: float | None = None, is_retryable: bool | None = None) -> None

Bases: LLMError

Raised when the provider refuses the call for now, in a way that clears by retrying without anyone acting: a per-minute or other rolling-window limit, a 429, a 402 that says how long to wait and names no quota, or on jaz.llm.GitHubCopilotLLM a per-session spending cap that a new session resets. A limit that needs someone to act, or lasts until a calendar reset, is a QuotaExceededError instead, and the provider’s quota code says so at a 429 too.

Retried by default, after the wait the provider asks for (retry_after); a wait longer than RetryPolicy.retry_after_max is not retried, and retry_after says when to try again.

Bases: LLMError

Raised when the account’s or project’s quota, credit or spend limit is used up, so the call cannot succeed until someone acts (adds credit, raises a budget, enables billing) or the quota resets on the calendar (a daily quota, a monthly allowance or spend cap). A limit that clears by retrying without anyone acting (a rolling window, a stated wait, a new session) is a RateLimitError instead.

Not retried by default, since resending cannot fix it, unless the provider’s x-should-retry header says to. To keep retrying while someone tops up the account, opt in: RetryPolicy(extra_retryable_exceptions=[QuotaExceededError]).

Every backend raises it for a 402 status unless the 402 says how long to wait and names no quota, or, on jaz.llm.GitHubCopilotLLM, is the per-session spending cap on a reused session that spent on earlier turns; and for the provider’s own quota codes at any other status. jaz.llm.LiteLLM also recognizes a provider’s documented quota message, and raises it when litellm.max_budget is spent. An error a backend does not recognize as a quota surfaces as whatever class its status maps to, typically RateLimitError or BadRequestError.

Bases: LLMError

Raised when API authentication fails (invalid API key, etc.).

Not retried by default - the API key or credentials need to be fixed.

Bases: LLMError

Raised when the request went to the wrong place, so the model name or the base URL has to change.

Usually a 404, with two realistic causes:

  • the model name does not exist, or names a model the account is not entitled to — by far the common case, and the first thing to check. Most providers answer both with a 404 (OpenAI’s model_not_found reads “does not exist or you do not have access to it”); some send a 403 for the entitlement (PermissionDeniedError), Anthropic and Bedrock among them;
  • the base URL is wrong, so the route itself is missing: anyone pointed at vLLM, a LiteLLM proxy, Ollama, or Azure can 404 on the path rather than the model.

On Azure the model name is the deployment name, and a wrong one is a 404 too.

Also raised for a redirect (a 3xx) the backend does not follow, and for redirects that never end, and for OpenAI’s model_not_found code whatever the status. A provider that answers an unknown model with a plain 400 raises BadRequestError instead. On LiteLLM, a 301, 302 or 303 is followed as a GET, as browsers and httpx do, so it surfaces as whatever the new address answers.

Not retried by default — the model name or base URL has to be corrected.

Bases: LLMError

Raised when the provider answers 403 and nothing in its response says otherwise: the key is valid — an invalid one is 401, AuthenticationError — but is not permitted the request.

What a 403 covers differs by provider (a key outside the project’s scope, Bedrock’s model access not enabled, OpenAI’s unsupported region), so the class is the status’s verdict rather than one fix. A 403 whose body the backend recognizes as a content block, a quota or a bad credential raises ContentPolicyViolationError, QuotaExceededError or AuthenticationError instead; OpenRouter’s permission_denied covers a key’s missing permission and a guardrail block alike, and arrives as this. A model the account is not entitled to is a 404 (NotFoundError) or a 400 on most providers, not a 403. Also raised where the provider says the account’s standing is the problem whatever the status, such as a Gemini response stopped with PUP_LIMITED_DISABLED or Bedrock’s 404 for an account that has not submitted Anthropic’s use-case form.

Not retried by default — a permission has to be granted, or the account’s standing restored.

Bases: LLMError

Raised when what was asked has to change, so resending it unchanged usually fails the same way: the provider rejects the request, the backend refuses to send it, or (as ContentPolicyViolationError) the provider blocks the prompt or the response. Its subclasses name a cause, such as ContextWindowExceededError for an input too long for the model. Where nothing more is known the status decides: any 4xx with no class of its own raises it, registered in HTTP or not (an invalid parameter, a request too large, Groq’s 498), except 408, 409 and 499, which are retried as ServerError (on jaz.llm.SGLangLLM a 499 is RequestAbortedError). Where the backend recognizes them, an account out of credit raises QuotaExceededError instead, and a wrong model name or address NotFoundError.

Not retried by default. The message carries the reason, the provider’s where it sent one.

Bases: BadRequestError

Raised when a request parameter or backend setting is not supported, before anything is sent: jaz.llm.LiteLLM raises it for a parameter LiteLLM cannot translate for the provider (set drop_params=True to drop such parameters instead), and for a LiteLLM global the backend refuses, such as litellm.num_retries.

A BadRequestError, so except BadRequestError catches it. Not retried by default.

Bases: BadRequestError

Raised when the LLM input exceeds the model’s context window.

A BadRequestError, so except BadRequestError catches it. Not retried by default, since the same input will not fit.

Bases: BadRequestError

Raised when the provider blocks a prompt or response under its content or usage policy, or the model refuses it: as an error status, or, on jaz.llm.LiteLLM and jaz.llm.GitHubCopilotLLM, as a refusal or content filter signaled on a successful response, where status_code is None since no error status came back. Models LiteLLM routes through its Responses API bridge (such as gpt-5-pro and the -codex models) lose a refusal, which arrives as an ordinary response; their content filter does raise. On jaz.llm.LiteLLM it is also raised, with status_code None, when a guardrail LiteLLM runs blocks the call. LiteLLM runs guardrails on async calls (jaz.ainvoke), and on sync calls only for the models on that Responses API bridge.

A BadRequestError, so except BadRequestError catches it. Not retried by default. The same input can pass when resent, so to retry it add it to RetryPolicy.extra_retryable_exceptions.

Bases: LLMError

Raised when the provider fails to answer the request properly: a server error (5xx), a 408 (Request Timeout) or 409 (Conflict), which the openai and anthropic SDKs also retry, a 499 outside jaz.llm.SGLangLLM, a response that is not a valid completion, or a failure no more specific class describes (such as a status outside 4xx and 5xx). A failed transport, a timeout included, raises APIConnectionError instead.

A 5xx raises the subclass InternalServerError; on jaz.llm.SGLangLLM, a success status whose response is not a valid completion raises APIResponseValidationError.

Retried by default, with its subclasses (it is in BaseLLM.retryable_exceptions). On jaz.llm.LiteLLM the original LiteLLM exception is chained as __cause__.

Bases: ServerError

Raised when the provider answers with a server error status (5xx). A 529, Anthropic’s “overloaded”, raises the subclass OverloadedError.

Retryable, as a ServerError; key RetryPolicy.limits on it to cap 5xx answers apart from invalid responses.

Bases: InternalServerError

Raised when the provider answers that it is overloaded (HTTP 529, as Anthropic sends).

Retryable, as an InternalServerError.

Bases: ServerError

Raised when the provider answers with a success status but the response is not a valid completion, such as a body that is not JSON, one missing a field the backend needs, an error object in place of a completion, a tool call when no tools were offered, or a response that fails a JSON schema the caller asked the backend to enforce (litellm.enable_json_schema_validation on jaz.llm.LiteLLM). status_code is the success status where the backend saw it, else None. jaz.llm.LiteLLM detects only a body that is not JSON; JSON of the wrong shape surfaces as whatever class LiteLLM’s own error maps to, which on some providers is not retried.

Retryable, as a ServerError: a garbled response is usually transient, and another sample may pass the schema.

Bases: LLMError, ConnectionError

Raised when the transport fails, rather than the server answering with an error: the endpoint cannot be reached, the request cannot be sent, or no usable response comes back (the connection drops, what arrives cannot be parsed or decoded, such as a body whose compression is broken), or the call times out (the subclass APITimeoutError).

Retried by default; key RetryPolicy.limits on APIConnectionError to cap it, timeouts included. If it persists, check the network and the endpoint the backend talks to (its base URL, or for a CLI-backed backend, the CLI). It is also a builtin ConnectionError, so except ConnectionError (and except OSError) catches it.

Bases: APIConnectionError, TimeoutError

Raised when an LLM call times out before the provider answers.

An APIConnectionError, so except APIConnectionError and limits={APIConnectionError: n} cover it too; key RetryPolicy.limits on APITimeoutError to cap timeouts on their own, or raise the backend’s timeout. Retried by default. It is also a builtin TimeoutError (and so an OSError), so except TimeoutError catches it.

Bases: LLMError

Raised when the server reports the request as aborted: on jaz.llm.SGLangLLM, SGLang 0.5.17’s 499 for a request aborted before it was scheduled, or a request SGLang aborted (a pause with mode="abort", a weight update, /abort_request) and answered with a 200 carrying the partial generation, which is then in body. SGLang answers a grammar failure the same way, so that raises it too, though nobody cancelled it.

Not retried by default, since an abort is normally meant to stop the request. To retry it, add it to RetryPolicy.extra_retryable_exceptions; the retry re-sends the original prompt from scratch and does not continue from the partial generation. A server’s x-should-retry header still decides where it sends one. Raised in a sub-invoke, it reaches the parent’s code as an ordinary exception, which can catch it and go on querying.

is_fatal(e: BaseException) -> bool

Whether e should end the whole agent run instead of becoming feedback.

Consulted at every REPL exec boundary: a caught exception either re-raises out of exec and propagates out of the invoke (fatal) or is rendered as a recoverable Continue.

Two rules, in this order:

  1. Anything rooted outside Exception is fatal — KeyboardInterrupt, SystemExit, GeneratorExit, asyncio.CancelledError. This is the recoverable-vs-fatal split the language already encodes, not a hand-maintained list.
  2. FatalError is fatal, explicitly — including when it is nested anywhere inside a (Base)ExceptionGroup, at any depth. Containment, not majority: a fatal error bundled with ordinary ones stays fatal.

That is the only carve-out. MemoryError is not special-cased (CPython roots it under Exception because OOM can be recoverable — the iteration and budget caps backstop a retry loop), and neither is AssertionError — an agent’s own assert stays recoverable. To make a third-party error fatal, rewrap it as a FatalError at the raise site rather than extending this function.