Skip to content

strands.types.exceptions

Exception-related type definitions for the SDK.

ContextWindowOverflowException

Bases: Exception

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.

Source code in strands/types/exceptions.py 
38
39
40
41
42
43
44
45
46
class ContextWindowOverflowException(Exception):
    """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.
    """

    pass

EventLoopException

Bases: Exception

Exception raised by the event loop.

Source code in strands/types/exceptions.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
class EventLoopException(Exception):
    """Exception raised by the event loop."""

    def __init__(self, original_exception: Exception, request_state: Any = None) -> None:
        """Initialize exception.

        Args:
            original_exception: The original exception that was raised.
            request_state: The state of the request at the time of the exception.
        """
        self.original_exception = original_exception
        self.request_state = request_state if request_state is not None else {}
        super().__init__(str(original_exception))

__init__(original_exception, request_state=None)

Initialize exception.

Parameters:

Name Type Description Default
original_exception Exception

The original exception that was raised.

 required
request_state Any

The state of the request at the time of the exception.

 None
Source code in strands/types/exceptions.py 
 9
10
11
12
13
14
15
16
17
18
def __init__(self, original_exception: Exception, request_state: Any = None) -> None:
    """Initialize exception.

    Args:
        original_exception: The original exception that was raised.
        request_state: The state of the request at the time of the exception.
    """
    self.original_exception = original_exception
    self.request_state = request_state if request_state is not None else {}
    super().__init__(str(original_exception))

MCPClientInitializationError

Bases: Exception

Raised when the MCP server fails to initialize properly.

Source code in strands/types/exceptions.py 
49
50
51
52
class MCPClientInitializationError(Exception):
    """Raised when the MCP server fails to initialize properly."""

    pass

MaxTokensReachedException

Bases: Exception

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.

Source code in strands/types/exceptions.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
class MaxTokensReachedException(Exception):
    """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.
    """

    def __init__(self, message: str):
        """Initialize the exception with an error message and the incomplete message object.

        Args:
            message: The error message describing the token limit issue
        """
        super().__init__(message)

__init__(message)

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

Parameters:

Name Type Description Default
message str

The error message describing the token limit issue

 required
Source code in strands/types/exceptions.py 
29
30
31
32
33
34
35
def __init__(self, message: str):
    """Initialize the exception with an error message and the incomplete message object.

    Args:
        message: The error message describing the token limit issue
    """
    super().__init__(message)

ModelThrottledException

Bases: Exception

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.

Source code in strands/types/exceptions.py 
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
class ModelThrottledException(Exception):
    """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.
    """

    def __init__(self, message: str) -> None:
        """Initialize exception.

        Args:
            message: The message from the service that describes the throttling.
        """
        self.message = message
        super().__init__(message)

    pass

__init__(message)

Initialize exception.

Parameters:

Name Type Description Default
message str

The message from the service that describes the throttling.

 required
Source code in strands/types/exceptions.py 
62
63
64
65
66
67
68
69
def __init__(self, message: str) -> None:
    """Initialize exception.

    Args:
        message: The message from the service that describes the throttling.
    """
    self.message = message
    super().__init__(message)

SessionException

Bases: Exception

Exception raised when session operations fail.

Source code in strands/types/exceptions.py 
74
75
76
77
class SessionException(Exception):
    """Exception raised when session operations fail."""

    pass

StructuredOutputException

Bases: Exception

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

Source code in strands/types/exceptions.py 
86
87
88
89
90
91
92
93
94
95
96
class StructuredOutputException(Exception):
    """Exception raised when structured output validation fails after maximum retry attempts."""

    def __init__(self, message: str):
        """Initialize the exception with details about the failure.

        Args:
            message: The error message describing the structured output failure
        """
        self.message = message
        super().__init__(message)

__init__(message)

Initialize the exception with details about the failure.

Parameters:

Name Type Description Default
message str

The error message describing the structured output failure

 required
Source code in strands/types/exceptions.py 
89
90
91
92
93
94
95
96
def __init__(self, message: str):
    """Initialize the exception with details about the failure.

    Args:
        message: The error message describing the structured output failure
    """
    self.message = message
    super().__init__(message)

ToolProviderException

Bases: Exception

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

Source code in strands/types/exceptions.py 
80
81
82
83
class ToolProviderException(Exception):
    """Exception raised when a tool provider fails to load or cleanup tools."""

    pass