Exceptions

Custom exception hierarchy for Arena client errors. Provides structured error messages with Python/CLI hints and automatic internal-URL sanitization.

Base

class agilerl.arena.exceptions.ArenaError

Base exception for all Arena client errors.

classmethod enable_cli_mode() → None

Switch all Arena exceptions to CLI-friendly messages.

Authentication Errors

class agilerl.arena.exceptions.ArenaAuthError(message: str, *, sdk_hint: str = '', cli_hint: str = '')

Raised when authentication fails or credentials are missing/expired.

class agilerl.arena.exceptions.ArenaTimeoutError(message: str, *, sdk_hint: str = '', cli_hint: str = '')

Raised when the device-flow login times out waiting for user authorization.

API Errors

class agilerl.arena.exceptions.ArenaAPIError(detail: str, *, status_code: int = 0, extras: dict[str, Any] | None = None, sdk_hint: str = '', cli_hint: str = '')

Raised when the Arena API returns a non-2xx response.

Parameters:

• detail – Human-readable error description.

• status_code – HTTP status code from the API response.

• extras – Supplementary context from the error body.

• sdk_hint – Guidance shown when running from the Python SDK.

• cli_hint – Guidance shown when running from the CLI.

classmethod from_response_body(raw: str, *, status_code: int = 0) → ArenaAPIError

Build an instance from a raw HTTP response body string.

Handles plain text, JSON, broken JSON (embedded newlines), nested JSON-in-string envelopes, and NDJSON error lines.

class agilerl.arena.exceptions.ArenaValidationError(detail: str, *, status_code: int = 0, extras: dict[str, Any] | None = None, sdk_hint: str = '', cli_hint: str = '')

Raised when environment validation fails or client arguments are invalid.

class agilerl.arena.exceptions.ArenaInferenceError(detail: str, *, status_code: int = 0, extras: dict[str, Any] | None = None, sdk_hint: str = '', cli_hint: str = '')

Raised when an Arena inference deployment request fails or inputs are invalid.

class agilerl.arena.exceptions.ArenaTrainingError(detail: str, *, status_code: int = 0, extras: dict[str, Any] | None = None, sdk_hint: str = '', cli_hint: str = '')

Raised when a training job submission or execution fails.

classmethod from_response_body(raw: str, *, status_code: int = 0) → ArenaAPIError

Promote to ArenaEnvironmentNotFoundError when applicable.