strands.types.exceptions

Exception-related type definitions for the SDK.

EventLoopException

class EventLoopException(Exception)

Defined in: src/strands/types/exceptions.py:6

Exception raised by the event loop.

__init__

def __init__(original_exception: Exception, request_state: Any = None) -> None

Defined in: src/strands/types/exceptions.py:9

Initialize exception.

Arguments:

• original_exception - The original exception that was raised.
• request_state - The state of the request at the time of the exception.

MaxTokensReachedException

class MaxTokensReachedException(Exception)

Defined in: src/strands/types/exceptions.py:21

Exception raised when the model reaches its maximum token generation limit.

This exception is raised when the model stops generating tokens because it has reached the maximum number of tokens allowed for output generation. This can occur when the model’s max_tokens parameter is set too low for the complexity of the response, or when the model naturally reaches its configured output limit during generation.

__init__

def __init__(message: str)

Defined in: src/strands/types/exceptions.py:29

Initialize the exception with an error message and the incomplete message object.

Arguments:

• message - The error message describing the token limit issue

ContextWindowOverflowException

class ContextWindowOverflowException(Exception)

Defined in: src/strands/types/exceptions.py:38

Exception raised when the context window is exceeded.

This exception is raised when the input to a model exceeds the maximum context window size that the model can handle. This typically occurs when the combined length of the conversation history, system prompt, and current message is too large for the model to process.

MCPClientInitializationError

class MCPClientInitializationError(Exception)

Defined in: src/strands/types/exceptions.py:49

Raised when the MCP server fails to initialize properly.

ModelThrottledException

class ModelThrottledException(Exception)

Defined in: src/strands/types/exceptions.py:55

Exception raised when the model is throttled.

This exception is raised when the model is throttled by the service. This typically occurs when the service is throttling the requests from the client.

__init__

def __init__(message: str) -> None

Defined in: src/strands/types/exceptions.py:62

Initialize exception.

Arguments:

• message - The message from the service that describes the throttling.

SessionException

class SessionException(Exception)

Defined in: src/strands/types/exceptions.py:74

Exception raised when session operations fail.

ToolProviderException

class ToolProviderException(Exception)

Defined in: src/strands/types/exceptions.py:80

Exception raised when a tool provider fails to load or cleanup tools.

StructuredOutputException

class StructuredOutputException(Exception)

Defined in: src/strands/types/exceptions.py:86

Exception raised when structured output validation fails after maximum retry attempts.

__init__

def __init__(message: str)

Defined in: src/strands/types/exceptions.py:89

Initialize the exception with details about the failure.

Arguments:

• message - The error message describing the structured output failure

ConcurrencyException

class ConcurrencyException(Exception)

Defined in: src/strands/types/exceptions.py:99

Exception raised when concurrent invocations are attempted on an agent instance.

Agent instances maintain internal state that cannot be safely accessed concurrently. This exception is raised when an invocation is attempted while another invocation is already in progress on the same agent instance.