Error Handling & Exceptions
Relevant source files
The following files were used as context for generating this wiki page:
- osmosis_ai/rollout/core/exceptions.py
- osmosis_ai/rollout/validator.py
- osmosis_ai/rollout/tools.py (referred via osmosis_ai/rollout/__init__.py)
- osmosis_ai/rubric_eval.py (referred via osmosis_ai/__init__.py)
- osmosis_ai/rubric_types.py (referred via osmosis_ai/__init__.py)
- osmosis_ai/auth/local_server.py
- tests/test_rollout_exceptions.py
The Osmosis SDK implements a structured hierarchy of exceptions and error-handling mechanisms to manage failures across its primary workflows: remote rollout execution, rubric evaluation, authentication, and implementation validation. The system distinguishes between retryable server-side issues and non-retryable client-side validation errors, ensuring robust communication between the SDK, the Osmosis Platform, and LLM providers.
Sources: osmosis_ai/rollout/core/exceptions.py:1-25, osmosis_ai/__init__.py:10-14
Rollout SDK Exception Hierarchy
The Rollout SDK uses a centralized exception hierarchy rooted in OsmosisRolloutError. This structure allows developers to catch all rollout-related issues or target specific failure modes such as network transport issues or tool execution failures.
The diagram above illustrates the inheritance relationship where specific operational errors inherit from the base rollout error class.
Sources: osmosis_ai/rollout/core/exceptions.py:28-124, tests/test_rollout_exceptions.py:105-112
Rollout Error Types and Descriptions
| Exception Class | Category | Description |
|---|---|---|
OsmosisTransportError | Network | Raised during network failures, DNS resolution issues, or connection refusals. |
OsmosisServerError | 5xx Server | Indicates a server-side failure. Includes a status_code (500-599) and is generally considered retryable. |
OsmosisValidationError | 4xx Client | Indicates invalid request format or authentication failure. Includes a status_code (400-499) and is not retryable. |
OsmosisTimeoutError | Timeout | Raised when operations exceed configured limits due to network latency or slow LLM generation. |
AgentLoopNotFoundError | Registry | Raised when a requested agent loop name is not found in the local registry. |
ToolExecutionError | Tooling | Errors occurring during the execution of a tool, capturing the tool name and call ID. |
Sources: osmosis_ai/rollout/core/exceptions.py:41-110, tests/test_rollout_exceptions.py:34-75
Rubric Evaluation Errors
Rubric evaluation involves interactions with external LLM providers via LiteLLM. Errors in this module are specific to model availability, API credentials, and provider-side request failures.
- MissingAPIKeyError: Raised when a required API key (e.g.,
OPENAI_API_KEY) is missing from the environment or configuration. - ModelNotFoundError: Reserved for scenarios where the specified model identifier does not exist on the provider's platform.
- ProviderRequestError: A general exception for remote failures returned by the LLM provider during evaluation.
Sources: osmosis_ai/__init__.py:10-12, README.md:88-100
Validation and Logic Errors
The SDK provides specialized error types for validating implementation contracts, particularly for RolloutAgentLoop subclasses.
Agent Loop Validation
The validate_agent_loop utility returns a ValidationResult containing a list of ValidationError objects. If validation is enforced, the SDK raises an AgentLoopValidationError.
Validation logic ensures the agent loop implementation adheres to the required protocol before the server starts.
Sources: osmosis_ai/rollout/validator.py:73-210, osmosis_ai/rollout/server/serve.py
Tool Argument Parsing
When processing tool calls, the SDK validates that arguments are provided in a valid JSON format or as a dictionary. Failure to parse these arguments results in a ToolArgumentError.
# From osmosis_ai/rollout/tools.py (usage pattern)
try:
args = parse_tool_arguments(tool_call["function"]["arguments"])
except ToolArgumentError as e:
# Captures parsing failures specifically for tool inputs
return create_tool_error_result(tool_call_id, str(e))
Sources: tests/test_rollout_tools.py:126-140, osmosis_ai/rollout/core/exceptions.py:122-124
Authentication and Callback Errors
The LocalAuthServer manages OAuth callbacks and handles errors related to state validation (CSRF protection) and timeout during the browser-based login flow.
- CSRF Protection: If the
stateparameter in the callback does not match theexpected_state, the server responds with an error page indicating an "Invalid state parameter." - Timeouts: The
wait_for_callbackmethod returns a "Authentication timed out" error if the user does not complete the login within the specified timeout (default 300s). - Verification Failures: If the token received from the callback fails backend verification, the server displays a "Login Failed" HTML page with a specific error message.
Sources: osmosis_ai/auth/local_server.py:44-78, osmosis_ai/auth/local_server.py:240-258
Summary
Error handling in the Osmosis SDK is designed to be both descriptive for end-users (via the CLI and HTML error pages) and programmatic for developers (via a strict exception hierarchy). By separating transport, validation, and execution errors, the SDK allows for sophisticated retry logic and implementation debugging, ensuring that LLM training workflows remain stable despite the inherent unpredictability of remote LLM providers and network environments.
Sources: osmosis_ai/rollout/core/exceptions.py:15-25, osmosis_ai/auth/local_server.py:150-180