Skip to content

Exceptions

The Incus Python SDK provides a set of exception classes for handling errors that may occur when interacting with the Incus API.

Usage

from incus_sdk import Client
from incus_sdk.exceptions import IncusNotFoundError, IncusAPIError

async def main():
    try:
        async with Client() as client:
            # Try to get a non-existent instance
            instance = await client.instances.get("non-existent-instance")
    except IncusNotFoundError as e:
        print(f"Instance not found: {e.message}")
    except IncusAPIError as e:
        print(f"API error: {e.message} (Status code: {e.status_code})")

Exception Hierarchy

All exceptions in the Incus Python SDK inherit from the base IncusError class:

IncusError
├── IncusAPIError
│   ├── IncusNotFoundError
│   ├── IncusAuthenticationError
│   └── IncusPermissionError
├── IncusConnectionError
└── IncusOperationError

Class Documentation

incus_sdk.exceptions.IncusError

Bases: Exception

Base exception for all Incus errors.

Source code in incus_sdk/exceptions.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
class IncusError(Exception):
    """Base exception for all Incus errors."""

    def __init__(
        self,
        message: str,
        status_code: Optional[int] = None,
        response: Optional[Dict[str, Any]] = None,
    ):
        """
        Initialize a new IncusError.

        Args:
            message: Error message.
            status_code: HTTP status code.
            response: API response.
        """
        self.message = message
        self.status_code = status_code
        self.response = response
        super().__init__(message)

__init__(message, status_code=None, response=None)

Initialize a new IncusError.

Parameters:

Name Type Description Default
message str

Error message.

 required
status_code Optional[int]

HTTP status code.

 None
response Optional[Dict[str, Any]]

API response.

 None
Source code in incus_sdk/exceptions.py 
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
def __init__(
    self,
    message: str,
    status_code: Optional[int] = None,
    response: Optional[Dict[str, Any]] = None,
):
    """
    Initialize a new IncusError.

    Args:
        message: Error message.
        status_code: HTTP status code.
        response: API response.
    """
    self.message = message
    self.status_code = status_code
    self.response = response
    super().__init__(message)

incus_sdk.exceptions.IncusAPIError

Bases: IncusError

Exception raised when an API request fails.

Source code in incus_sdk/exceptions.py 
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
class IncusAPIError(IncusError):
    """Exception raised when an API request fails."""

    def __init__(
        self, message: str, status_code: int, response: Optional[Dict[str, Any]] = None
    ):
        """
        Initialize a new IncusAPIError.

        Args:
            message: Error message.
            status_code: HTTP status code.
            response: API response.
        """
        super().__init__(message, status_code, response)

__init__(message, status_code, response=None)

Initialize a new IncusAPIError.

Parameters:

Name Type Description Default
message str

Error message.

 required
status_code int

HTTP status code.

 required
response Optional[Dict[str, Any]]

API response.

 None
Source code in incus_sdk/exceptions.py 
34
35
36
37
38
39
40
41
42
43
44
45
def __init__(
    self, message: str, status_code: int, response: Optional[Dict[str, Any]] = None
):
    """
    Initialize a new IncusAPIError.

    Args:
        message: Error message.
        status_code: HTTP status code.
        response: API response.
    """
    super().__init__(message, status_code, response)

incus_sdk.exceptions.IncusConnectionError

Bases: IncusError

Exception raised when a connection to the Incus API fails.

Source code in incus_sdk/exceptions.py 
48
49
50
51
52
53
54
55
56
57
58
59
60
class IncusConnectionError(IncusError):
    """Exception raised when a connection to the Incus API fails."""

    def __init__(self, message: str, cause: Optional[Exception] = None):
        """
        Initialize a new IncusConnectionError.

        Args:
            message: Error message.
            cause: Original exception.
        """
        self.cause = cause
        super().__init__(message)

__init__(message, cause=None)

Initialize a new IncusConnectionError.

Parameters:

Name Type Description Default
message str

Error message.

 required
cause Optional[Exception]

Original exception.

 None
Source code in incus_sdk/exceptions.py 
51
52
53
54
55
56
57
58
59
60
def __init__(self, message: str, cause: Optional[Exception] = None):
    """
    Initialize a new IncusConnectionError.

    Args:
        message: Error message.
        cause: Original exception.
    """
    self.cause = cause
    super().__init__(message)

incus_sdk.exceptions.IncusOperationError

Bases: IncusError

Exception raised when an operation fails.

Source code in incus_sdk/exceptions.py 
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
class IncusOperationError(IncusError):
    """Exception raised when an operation fails."""

    def __init__(
        self, message: str, operation_id: str, response: Optional[Dict[str, Any]] = None
    ):
        """
        Initialize a new IncusOperationError.

        Args:
            message: Error message.
            operation_id: ID of the failed operation.
            response: Operation response.
        """
        self.operation_id = operation_id
        super().__init__(message, response=response)

__init__(message, operation_id, response=None)

Initialize a new IncusOperationError.

Parameters:

Name Type Description Default
message str

Error message.

 required
operation_id str

ID of the failed operation.

 required
response Optional[Dict[str, Any]]

Operation response.

 None
Source code in incus_sdk/exceptions.py 
66
67
68
69
70
71
72
73
74
75
76
77
78
def __init__(
    self, message: str, operation_id: str, response: Optional[Dict[str, Any]] = None
):
    """
    Initialize a new IncusOperationError.

    Args:
        message: Error message.
        operation_id: ID of the failed operation.
        response: Operation response.
    """
    self.operation_id = operation_id
    super().__init__(message, response=response)

incus_sdk.exceptions.IncusNotFoundError

Bases: IncusAPIError

Exception raised when a resource is not found.

Source code in incus_sdk/exceptions.py 
81
82
83
84
85
86
87
88
89
90
91
92
class IncusNotFoundError(IncusAPIError):
    """Exception raised when a resource is not found."""

    def __init__(self, message: str, response: Optional[Dict[str, Any]] = None):
        """
        Initialize a new IncusNotFoundError.

        Args:
            message: Error message.
            response: API response.
        """
        super().__init__(message, 404, response)

__init__(message, response=None)

Initialize a new IncusNotFoundError.

Parameters:

Name Type Description Default
message str

Error message.

 required
response Optional[Dict[str, Any]]

API response.

 None
Source code in incus_sdk/exceptions.py 
84
85
86
87
88
89
90
91
92
def __init__(self, message: str, response: Optional[Dict[str, Any]] = None):
    """
    Initialize a new IncusNotFoundError.

    Args:
        message: Error message.
        response: API response.
    """
    super().__init__(message, 404, response)

incus_sdk.exceptions.IncusAuthenticationError

Bases: IncusAPIError

Exception raised when authentication fails.

Source code in incus_sdk/exceptions.py 
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
class IncusAuthenticationError(IncusAPIError):
    """Exception raised when authentication fails."""

    def __init__(
        self,
        message: str,
        status_code: int = 401,
        response: Optional[Dict[str, Any]] = None,
    ):
        """
        Initialize a new IncusAuthenticationError.

        Args:
            message: Error message.
            status_code: HTTP status code.
            response: API response.
        """
        super().__init__(message, status_code, response)

__init__(message, status_code=401, response=None)

Initialize a new IncusAuthenticationError.

Parameters:

Name Type Description Default
message str

Error message.

 required
status_code int

HTTP status code.

 401
response Optional[Dict[str, Any]]

API response.

 None
Source code in incus_sdk/exceptions.py 
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
def __init__(
    self,
    message: str,
    status_code: int = 401,
    response: Optional[Dict[str, Any]] = None,
):
    """
    Initialize a new IncusAuthenticationError.

    Args:
        message: Error message.
        status_code: HTTP status code.
        response: API response.
    """
    super().__init__(message, status_code, response)

incus_sdk.exceptions.IncusPermissionError

Bases: IncusAPIError

Exception raised when permission is denied.

Source code in incus_sdk/exceptions.py 
115
116
117
118
119
120
121
122
123
124
125
126
class IncusPermissionError(IncusAPIError):
    """Exception raised when permission is denied."""

    def __init__(self, message: str, response: Optional[Dict[str, Any]] = None):
        """
        Initialize a new IncusPermissionError.

        Args:
            message: Error message.
            response: API response.
        """
        super().__init__(message, 403, response)

__init__(message, response=None)

Initialize a new IncusPermissionError.

Parameters:

Name Type Description Default
message str

Error message.

 required
response Optional[Dict[str, Any]]

API response.

 None
Source code in incus_sdk/exceptions.py 
118
119
120
121
122
123
124
125
126
def __init__(self, message: str, response: Optional[Dict[str, Any]] = None):
    """
    Initialize a new IncusPermissionError.

    Args:
        message: Error message.
        response: API response.
    """
    super().__init__(message, 403, response)

Exception Handling

When using the Incus Python SDK, it's important to handle exceptions properly to provide a good user experience. Here are some common exceptions you might encounter:

IncusNotFoundError

This exception is raised when a resource (e.g., instance, image, network) is not found.

try:
    instance = await client.instances.get("non-existent-instance")
except IncusNotFoundError as e:
    print(f"Instance not found: {e.message}")

IncusAuthenticationError

This exception is raised when authentication fails, such as when using invalid credentials.

try:
    async with Client(cert=("invalid-cert.crt", "invalid-key.key")) as client:
        await client.connect()
except IncusAuthenticationError as e:
    print(f"Authentication failed: {e.message}")

IncusPermissionError

This exception is raised when the authenticated user does not have permission to perform an action.

try:
    await client.instances.create(
        name="my-instance",
        source={"type": "image", "alias": "ubuntu/22.04"}
    )
except IncusPermissionError as e:
    print(f"Permission denied: {e.message}")

IncusOperationError

This exception is raised when an operation fails.

try:
    await client.instances.start("my-instance", wait=True)
except IncusOperationError as e:
    print(f"Operation failed: {e.message}")
    print(f"Operation ID: {e.operation_id}")

IncusConnectionError

This exception is raised when a connection to the Incus API fails.

try:
    async with Client(endpoint="https://invalid-endpoint:8443") as client:
        await client.connect()
except IncusConnectionError as e:
    print(f"Connection failed: {e.message}")
    if e.cause:
        print(f"Cause: {e.cause}")