airflow.providers.common.ai.exceptions¶

Exceptions¶

`HITLMaxIterationsError`	Raised when the HITL review loop exhausts max iterations without approval or rejection.
`LLMFileAnalysisError`	Base class for file-analysis validation errors.
`LLMFileAnalysisUnsupportedFormatError`	Raised when a file format is not supported by LLM file analysis.
`LLMFileAnalysisLimitExceededError`	Raised when file-analysis safety limits are exceeded.
`LLMFileAnalysisMultimodalRequiredError`	Raised when image/PDF inputs are used without `multi_modal=True`.
`LowConfidenceError`	Raised by an LLM operator whose `DecisionPolicy` says `on_uncertain="fail"`.
`ManagedAgentInvocationError`	Raised when a managed agent cannot be reached and retrying will not help.
`LLMBatchInputError`	Base class for `@task.llm_batch` errors detected before a batch is submitted.
`LLMBatchLimitExceededError`	Raised when a batch exceeds a provider's request-count or payload-size limit.
`LLMBatchModelMismatchError`	Raised when a per-request `model` override resolves to a different adapter than the batch.
`UnsupportedBatchProviderError`	Raised when the connection/model combination has no batch adapter at all.
`BatchProviderNotYetSupportedError`	Raised for a connection type common.ai recognizes but does not yet support for batch.
`LLMBatchStaleStateError`	Raised on retry when the recorded input fingerprint no longer matches and `on_stale_state="fail"`.
`LLMBatchOutputTypeError`	Raised when `output_type` itself cannot produce a JSON Schema (not a per-item validation failure).
`LLMBatchJobError`	Base class for `@task.llm_batch` errors detected after a batch is submitted.
`LLMBatchTimeoutError`	Raised when the wall-clock defer budget is exhausted before the batch reaches a terminal state.
`LLMBatchOrphanedIntentError`	Raised when an intent record has no matching batch and `on_orphaned_intent="fail"`.
`LLMBatchPartialFailureError`	Raised when `fail_on_partial_error=True` and any request did not produce a valid result.
`LLMBatchCancelledError`	Raised when the batch was cancelled (by `cancel_on_kill`/`cancel_on_timeout` or out of band).
`LLMBatchOrphanLookupError`	Raised when checking the provider for an orphaned batch failed.
`LLMBatchStateReadError`	Raised when the run-stable state file exists but cannot be read or parsed.

Module Contents¶

exception airflow.providers.common.ai.exceptions.HITLMaxIterationsError[source]¶

Bases: airflow.providers.common.compat.sdk.AirflowException

Raised when the HITL review loop exhausts max iterations without approval or rejection.

exception airflow.providers.common.ai.exceptions.LLMFileAnalysisError[source]¶

Bases: ValueError

Base class for file-analysis validation errors.

exception airflow.providers.common.ai.exceptions.LLMFileAnalysisUnsupportedFormatError[source]¶

Bases: LLMFileAnalysisError

Raised when a file format is not supported by LLM file analysis.

exception airflow.providers.common.ai.exceptions.LLMFileAnalysisLimitExceededError[source]¶

Bases: LLMFileAnalysisError

Raised when file-analysis safety limits are exceeded.

exception airflow.providers.common.ai.exceptions.LLMFileAnalysisMultimodalRequiredError[source]¶

Bases: LLMFileAnalysisUnsupportedFormatError

Raised when image/PDF inputs are used without multi_modal=True.

exception airflow.providers.common.ai.exceptions.LowConfidenceError[source]¶

Bases: ValueError

Raised by an LLM operator whose DecisionPolicy says on_uncertain="fail".

The model’s confidence in its answer was under the policy’s bar, or the model reported no confidence at all. Airflow’s default retry behaviour retries it like any other exception; match it in a retry rule to fail fast instead.

exception airflow.providers.common.ai.exceptions.ManagedAgentInvocationError[source]¶

Bases: RuntimeError

Raised when a managed agent cannot be reached and retrying will not help.

Reserved for terminal conditions – bad credentials, a missing agent, a revoked quota. Transient failures should propagate unchanged so Airflow’s task-level retry handles them, and requests the model could fix by rephrasing should raise pydantic_ai.exceptions.ModelRetry instead.

exception airflow.providers.common.ai.exceptions.LLMBatchInputError[source]¶

Bases: ValueError

Base class for @task.llm_batch errors detected before a batch is submitted.

exception airflow.providers.common.ai.exceptions.LLMBatchLimitExceededError[source]¶

Bases: LLMBatchInputError

Raised when a batch exceeds a provider’s request-count or payload-size limit.

exception airflow.providers.common.ai.exceptions.LLMBatchModelMismatchError[source]¶

Bases: LLMBatchInputError

Raised when a per-request model override resolves to a different adapter than the batch.

exception airflow.providers.common.ai.exceptions.UnsupportedBatchProviderError[source]¶

Bases: LLMBatchInputError

Raised when the connection/model combination has no batch adapter at all.

exception airflow.providers.common.ai.exceptions.BatchProviderNotYetSupportedError[source]¶

Bases: LLMBatchInputError

Raised for a connection type common.ai recognizes but does not yet support for batch.

Distinct from UnsupportedBatchProviderError: that one means “this path does not exist”; this one means “this path is known but not built yet” (e.g. Azure OpenAI, Bedrock, Vertex).

exception airflow.providers.common.ai.exceptions.LLMBatchStaleStateError[source]¶

Bases: LLMBatchInputError

Raised on retry when the recorded input fingerprint no longer matches and on_stale_state="fail".

exception airflow.providers.common.ai.exceptions.LLMBatchOutputTypeError[source]¶

Bases: LLMBatchInputError

Raised when output_type itself cannot produce a JSON Schema (not a per-item validation failure).

exception airflow.providers.common.ai.exceptions.LLMBatchJobError[source]¶

Bases: RuntimeError

Base class for @task.llm_batch errors detected after a batch is submitted.

exception airflow.providers.common.ai.exceptions.LLMBatchTimeoutError[source]¶

Bases: LLMBatchJobError

Raised when the wall-clock defer budget is exhausted before the batch reaches a terminal state.

exception airflow.providers.common.ai.exceptions.LLMBatchOrphanedIntentError[source]¶

Bases: LLMBatchJobError

Raised when an intent record has no matching batch and on_orphaned_intent="fail".

A previous attempt crashed between submitting the batch and recording that it succeeded; provider-side recovery (find_orphaned_batch()) found nothing. Unlike a stale-fingerprint mismatch, there is no old batch id to cancel as a loss-limiting step here – resubmitting risks paying twice if the original request actually reached the provider and simply could not be recovered.

exception airflow.providers.common.ai.exceptions.LLMBatchPartialFailureError[source]¶

Bases: LLMBatchJobError

Raised when fail_on_partial_error=True and any request did not produce a valid result.

Covers provider-side errors, output-validation failures, expired, cancelled and missing requests alike; the manifest’s counts says which.

exception airflow.providers.common.ai.exceptions.LLMBatchCancelledError[source]¶

Bases: LLMBatchJobError

Raised when the batch was cancelled (by cancel_on_kill/cancel_on_timeout or out of band).

Whatever finished before the cancel is fetched and landed first, so the results file is complete for the requests that did run. The recorded state is deleted, so the next attempt submits a fresh batch instead of re-attaching to the cancelled one.

exception airflow.providers.common.ai.exceptions.LLMBatchOrphanLookupError[source]¶

Bases: LLMBatchJobError

Raised when checking the provider for an orphaned batch failed.

A previous attempt wrote an intent record but no batch id, and the lookup that would tell “the submit never reached the provider” apart from “it did, and is billing” raised. Neither answer is known, so the operator refuses to resubmit; the error is retryable.

exception airflow.providers.common.ai.exceptions.LLMBatchStateReadError[source]¶

Bases: LLMBatchJobError

Raised when the run-stable state file exists but cannot be read or parsed.

Distinct from “no recorded state” (a plain, expected None – see batch/state.py’s read_state): an I/O failure or a corrupt/malformed state file must never be silently treated as “safe to submit a new batch”, since that is exactly the condition that causes a duplicate, billable submission. This is deliberately retryable (a transient object-storage blip resolves on its own); a task that fails with this error should be retried, not have its state file deleted.