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