Exceptions Reference

All exception classes in anchor inherit from AstroContextError. Import them directly from the top-level package:

from anchor import (
    AstroContextError,
    PipelineExecutionError,
    TokenBudgetExceededError,
    RetrieverError,
    StorageError,
    FormatterError,
    IngestionError,
)

Hierarchy

Exception
 └── AstroContextError
      ├── PipelineExecutionError
      ├── TokenBudgetExceededError
      ├── RetrieverError
      ├── StorageError
      ├── FormatterError
      └── IngestionError

AstroContextError

Base exception for all anchor errors. Catch this to handle any library-level error in a single except clause.

PipelineExecutionError

Raised when the pipeline fails at a step with on_error="raise". Carries partial diagnostics so you can inspect what happened before the failure.

class PipelineExecutionError(AstroContextError):
    def __init__(self, message: str, diagnostics: dict[str, Any] | None = None) -> None:
        ...
    diagnostics: dict[str, Any]

Example

from anchor import ContextPipeline, PipelineExecutionError

try:
    result = pipeline.build("test")
except PipelineExecutionError as e:
    print(f"Failed at step: {e.diagnostics.get('failed_step')}")
    print(f"Steps completed: {e.diagnostics.get('steps', [])}")

TokenBudgetExceededError

Raised when the token budget is exceeded and no overflow strategy can handle it.

RetrieverError

Raised when a retriever encounters an error. For example, classified_retriever_step raises this when the classified label has no matching retriever and no default is configured.

StorageError

Raised when a storage backend (context store, document store, vector store) encounters an error.

FormatterError

Raised when formatting context fails. The pipeline wraps formatter exceptions in this class.

IngestionError

Raised when document ingestion (parsing or chunking) fails.

See Also

• Pipeline Guide -- error handling patterns
• Pipeline API Reference -- on_error parameter on steps