fastrag.exceptions

Exception hierarchy.

Every error raised by the SDK derives from FastragError, so a caller can catch the whole package with one except. TransientError is a mixin rather than a branch of the tree, so an exception can be both typed by origin — a fetch failure, an embedding failure — and marked retryable.

describe_error() is the counterpart for reporting one: not every exception that reaches a failure handler is one of ours, and a third-party exception raised with no arguments formats as an empty string.

Functions

describe_error(error)

Format error for a human, never as an empty string.

Exceptions

CacheError	The step cache could not be read or written.
ChatError	A chat completion request failed.
ChatStoreError	A chat store operation (session, chat, or message) could not be completed.
ChunkingError	A document could not be chunked.
ConfigurationError	Invalid arguments, a missing optional dependency, or a bad template.
ContextLengthError	The prompt exceeded the model's context window.
EmbeddingError	An embedding request failed.
FastragError	Base class for every error raised by Fastrag.
FetchError	A resource could not be fetched.
ParseError	A resource could not be parsed.
RerankError	A rerank request failed.
ServiceError	A client for something outside the process failed.
SourceError	A source could not be turned into documents.
TransientCacheError	A cache operation failed on lock contention or a lost connection.
TransientChatError	A chat completion failed for a reason that may succeed on retry.
TransientChatStoreError	A chat store operation failed on lock contention or a lost connection.
TransientEmbeddingError	An embedding failed for a reason that may succeed on retry.
TransientError	Mixin marking an error worth retrying.
TransientFetchError	A fetch failed for a reason that may succeed on retry (network, 5xx).
TransientParseError	Parsing failed because of a temporary model or network failure.
TransientRerankError	A rerank failed for a reason that may succeed on retry.
TransientVectorStoreError	A vector store operation failed for a reason that may succeed on retry.
VectorStoreError	A vector store operation failed.

exception fastrag.exceptions.FastragError

Bases: Exception

Base class for every error raised by Fastrag.

exception fastrag.exceptions.TransientError

Bases: FastragError

Mixin marking an error worth retrying.

Only exceptions carrying this mixin are retried by Policy: a timeout is transient, a malformed document is not.

exception fastrag.exceptions.ConfigurationError

Bases: FastragError

Invalid arguments, a missing optional dependency, or a bad template.

Always raised as early as possible — at construction, not at first use.

exception fastrag.exceptions.SourceError

Bases: FastragError

A source could not be turned into documents.

exception fastrag.exceptions.FetchError

Bases: SourceError

A resource could not be fetched.

exception fastrag.exceptions.TransientFetchError

Bases: FetchError, TransientError

A fetch failed for a reason that may succeed on retry (network, 5xx).

exception fastrag.exceptions.ParseError

Bases: SourceError

A resource could not be parsed.

exception fastrag.exceptions.TransientParseError

Bases: ParseError, TransientError

Parsing failed because of a temporary model or network failure.

exception fastrag.exceptions.ChunkingError

Bases: FastragError

A document could not be chunked.

exception fastrag.exceptions.ServiceError

Bases: FastragError

A client for something outside the process failed.

exception fastrag.exceptions.EmbeddingError

Bases: ServiceError

An embedding request failed.

exception fastrag.exceptions.TransientEmbeddingError

Bases: EmbeddingError, TransientError

An embedding failed for a reason that may succeed on retry.

exception fastrag.exceptions.ChatError

Bases: ServiceError

A chat completion request failed.

exception fastrag.exceptions.TransientChatError

Bases: ChatError, TransientError

A chat completion failed for a reason that may succeed on retry.

exception fastrag.exceptions.ContextLengthError

Bases: ChatError

The prompt exceeded the model’s context window.

Deliberately not a TransientError: retrying an over-long prompt produces the same failure, so Policy must not retry it.

exception fastrag.exceptions.RerankError

Bases: ServiceError

A rerank request failed.

exception fastrag.exceptions.TransientRerankError

Bases: RerankError, TransientError

A rerank failed for a reason that may succeed on retry.

exception fastrag.exceptions.VectorStoreError

Bases: ServiceError

A vector store operation failed.

exception fastrag.exceptions.TransientVectorStoreError

Bases: VectorStoreError, TransientError

A vector store operation failed for a reason that may succeed on retry.

exception fastrag.exceptions.CacheError

Bases: FastragError

The step cache could not be read or written.

exception fastrag.exceptions.TransientCacheError

Bases: CacheError, TransientError

A cache operation failed on lock contention or a lost connection.

exception fastrag.exceptions.ChatStoreError

Bases: FastragError

A chat store operation (session, chat, or message) could not be completed.

exception fastrag.exceptions.TransientChatStoreError

Bases: ChatStoreError, TransientError

A chat store operation failed on lock contention or a lost connection.

fastrag.exceptions.describe_error(error)

Format error for a human, never as an empty string.

f"{error}" is the obvious way to render the error on an ItemFailed or StepFailed, and it renders an exception raised with no arguments — TimeoutError(), asyncio.CancelledError(), a bare third-party sentinel — as nothing at all, turning a real failure into a blank line. This falls back to the exception’s type name in that case, and prefixes it otherwise, so a failure always says at minimum what kind of failure it was.

describe_error(TimeoutError())  # -> "TimeoutError"
describe_error(ParseError("bad xlsx"))  # -> "ParseError: bad xlsx"

Parameters:

error (BaseException) – The exception to describe.

Returns:

"<type>: <message>", or just "<type>" when the exception carries no message.

Return type:

str