Skip to content

exceptions

napt.exceptions

Exception hierarchy for NAPT.

This module defines a custom exception hierarchy for distinguishing between different types of errors. All exceptions inherit from NAPTError, allowing callers to catch all NAPT errors with a single except clause if needed.

NAPTError

Bases: Exception

Base exception for all NAPT errors.

All NAPT-specific exceptions inherit from this class, allowing callers to catch all NAPT errors with a single except clause if needed.

Source code in napt/exceptions.py 
25
26
27
28
29
30
31
32
class NAPTError(Exception):
    """Base exception for all NAPT errors.

    All NAPT-specific exceptions inherit from this class, allowing callers
    to catch all NAPT errors with a single except clause if needed.
    """

    pass

ConfigError

Bases: NAPTError

Raised for configuration-related errors.

This exception is raised when there are problems with:

  • YAML parse errors (syntax errors, invalid structure)
  • Missing required configuration fields (e.g., no apps defined, missing 'discovery.strategy' field)
  • Invalid strategy configuration (unknown strategy name, invalid strategy parameters)
  • Missing recipe files (file not found)
  • Recipe validation failures (invalid recipe structure, missing required app fields)
Example

Catching configuration errors: 

from napt.exceptions import ConfigError

try:
    config = load_effective_config(Path("invalid.yaml"))
except ConfigError as e:
    print(f"Config error: {e}")

Source code in napt/exceptions.py 
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
class ConfigError(NAPTError):
    """Raised for configuration-related errors.

    This exception is raised when there are problems with:

    - YAML parse errors (syntax errors, invalid structure)
    - Missing required configuration fields (e.g., no apps defined, missing
        'discovery.strategy' field)
    - Invalid strategy configuration (unknown strategy name, invalid strategy
        parameters)
    - Missing recipe files (file not found)
    - Recipe validation failures (invalid recipe structure, missing required
        app fields)

    Example:
        Catching configuration errors:
            ```python
            from napt.exceptions import ConfigError

            try:
                config = load_effective_config(Path("invalid.yaml"))
            except ConfigError as e:
                print(f"Config error: {e}")
            ```
    """

    pass

NetworkError

Bases: NAPTError

Raised for network/download-related errors.

This exception is raised when there are problems with:

  • Download failures (HTTP errors, connection timeouts, network unreachable)
  • API call failures (GitHub API errors, JSON API endpoint failures, authentication issues)
  • Network-related version extraction errors (API response parsing failures)
Example

Catching network errors: 

from napt.exceptions import NetworkError

try:
    result = discover_recipe(Path("recipe.yaml"), Path("./downloads"))
except NetworkError as e:
    print(f"Network error: {e}")

Source code in napt/exceptions.py 
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
class NetworkError(NAPTError):
    """Raised for network/download-related errors.

    This exception is raised when there are problems with:

    - Download failures (HTTP errors, connection timeouts, network
        unreachable)
    - API call failures (GitHub API errors, JSON API endpoint failures,
        authentication issues)
    - Network-related version extraction errors (API response parsing
        failures)

    Example:
        Catching network errors:
            ```python
            from napt.exceptions import NetworkError

            try:
                result = discover_recipe(Path("recipe.yaml"), Path("./downloads"))
            except NetworkError as e:
                print(f"Network error: {e}")
            ```
    """

    pass

PackagingError

Bases: NAPTError

Raised for packaging/build-related errors.

This exception is raised when there are problems with:

  • Build failures (PSADT template processing errors, file operations, directory creation failures)
  • Missing build tools (IntuneWinAppUtil.exe not found, PSADT template missing)
  • MSI extraction errors (failed to read MSI ProductVersion, unsupported MSI format)
  • Packaging operations (IntuneWinAppUtil.exe execution failures, invalid build directory structure)
  • Malformed .intunewin files (invalid ZIP structure, missing Detection.xml, missing required encryption fields)
Example

Catching packaging errors: 

from napt.exceptions import PackagingError

try:
    build_package(Path("recipe.yaml"), Path("./builds"))
except PackagingError as e:
    print(f"Packaging error: {e}")

Source code in napt/exceptions.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
class PackagingError(NAPTError):
    """Raised for packaging/build-related errors.

    This exception is raised when there are problems with:

    - Build failures (PSADT template processing errors, file operations,
        directory creation failures)
    - Missing build tools (IntuneWinAppUtil.exe not found, PSADT template
        missing)
    - MSI extraction errors (failed to read MSI ProductVersion, unsupported
        MSI format)
    - Packaging operations (IntuneWinAppUtil.exe execution failures, invalid
        build directory structure)
    - Malformed .intunewin files (invalid ZIP structure, missing Detection.xml,
        missing required encryption fields)

    Example:
        Catching packaging errors:
            ```python
            from napt.exceptions import PackagingError

            try:
                build_package(Path("recipe.yaml"), Path("./builds"))
            except PackagingError as e:
                print(f"Packaging error: {e}")
            ```
    """

    pass

StateError

Bases: NAPTError

Raised for persisted-state integrity errors.

This exception is raised when NAPT's own persisted state (the deployment state files under state/) is unreadable or invalid:

  • Corrupted deployment state files (invalid JSON)
  • Invalid deployment state fields (e.g., an unparseable ring entered_at timestamp)

Deployment state is authoritative and never auto-replaced; the error message says how to recover.

Example

Catching state errors: 

from napt.exceptions import StateError

try:
    state = load_deployment_state(path)
except StateError as e:
    print(f"State error: {e}")

Source code in napt/exceptions.py 
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
class StateError(NAPTError):
    """Raised for persisted-state integrity errors.

    This exception is raised when NAPT's own persisted state (the
    deployment state files under ``state/``) is unreadable or invalid:

    - Corrupted deployment state files (invalid JSON)
    - Invalid deployment state fields (e.g., an unparseable ring
        ``entered_at`` timestamp)

    Deployment state is authoritative and never auto-replaced; the error
    message says how to recover.

    Example:
        Catching state errors:
            ```python
            from napt.exceptions import StateError

            try:
                state = load_deployment_state(path)
            except StateError as e:
                print(f"State error: {e}")
            ```
    """

    pass

AuthError

Bases: NAPTError

Raised for authentication and authorization errors.

This exception is raised when there are problems with:

  • No credential available (no service principal / OIDC environment and no session from 'napt auth login')
  • Graph API 401 Unauthorized or 403 Forbidden responses
  • Interactive sign-in failure, timeout, or cancellation
  • A cached sign-in session that can no longer be refreshed
Example

Catching auth errors: 

from napt.exceptions import AuthError

try:
    result = upload_package(Path("recipe.yaml"))
except AuthError as e:
    print(f"Auth error: {e}")

Source code in napt/exceptions.py 
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
class AuthError(NAPTError):
    """Raised for authentication and authorization errors.

    This exception is raised when there are problems with:

    - No credential available (no service principal / OIDC environment and
        no session from 'napt auth login')
    - Graph API 401 Unauthorized or 403 Forbidden responses
    - Interactive sign-in failure, timeout, or cancellation
    - A cached sign-in session that can no longer be refreshed

    Example:
        Catching auth errors:
            ```python
            from napt.exceptions import AuthError

            try:
                result = upload_package(Path("recipe.yaml"))
            except AuthError as e:
                print(f"Auth error: {e}")
            ```
    """

    pass

NotModifiedError

Bases: Exception

Raised when a conditional HTTP request returns 304 Not Modified.

This exception is raised when download_file() receives HTTP 304, meaning the server has confirmed that the remote content has not changed since the last request. The function is expected to return a file on disk, and with a 304 response there is no file to return, so it raises instead.

Inherits from Exception (not NAPTError) so that broad catches of all NAPT errors do not suppress 304 responses. Callers that supply an ETag must handle this explicitly.

Example

Handling a conditional download: 

from napt.exceptions import NotModifiedError

try:
    result = download_file(url, dest, etag=cached_etag)
except NotModifiedError:
    # Server confirmed content unchanged, use the cached file
    pass

Source code in napt/exceptions.py 
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
class NotModifiedError(Exception):
    """Raised when a conditional HTTP request returns 304 Not Modified.

    This exception is raised when download_file() receives HTTP 304, meaning
    the server has confirmed that the remote content has not changed since the
    last request. The function is expected to return a file on disk, and with
    a 304 response there is no file to return, so it raises instead.

    Inherits from Exception (not NAPTError) so that broad catches of all NAPT
    errors do not suppress 304 responses. Callers that supply an ETag must
    handle this explicitly.

    Example:
        Handling a conditional download:
            ```python
            from napt.exceptions import NotModifiedError

            try:
                result = download_file(url, dest, etag=cached_etag)
            except NotModifiedError:
                # Server confirmed content unchanged, use the cached file
                pass
            ```
    """

    pass