Skip to content

prefect.exceptions

Prefect-specific exceptions.

Abort

Bases: PrefectSignal

Raised when the API sends an 'ABORT' instruction during state proposal.

Indicates that the run should exit immediately.

Source code in prefect/exceptions.py
284
285
286
287
288
289
class Abort(PrefectSignal):
    """
    Raised when the API sends an 'ABORT' instruction during state proposal.

    Indicates that the run should exit immediately.
    """

BlockMissingCapabilities

Bases: PrefectException

Raised when a block does not have required capabilities for a given operation.

Source code in prefect/exceptions.py
360
361
362
363
class BlockMissingCapabilities(PrefectException):
    """
    Raised when a block does not have required capabilities for a given operation.
    """

CancelledRun

Bases: PrefectException

Raised when the result from a cancelled run is retrieved and an exception is not attached.

This occurs when a string is attached to the state instead of an exception or if the state's data is null.

Source code in prefect/exceptions.py
79
80
81
82
83
84
85
86
class CancelledRun(PrefectException):
    """
    Raised when the result from a cancelled run is retrieved and an exception
    is not attached.

    This occurs when a string is attached to the state instead of an exception
    or if the state's data is null.
    """

CrashedRun

Bases: PrefectException

Raised when the result from a crashed run is retrieved.

This occurs when a string is attached to the state instead of an exception or if the state's data is null.

Source code in prefect/exceptions.py
60
61
62
63
64
65
66
class CrashedRun(PrefectException):
    """
    Raised when the result from a crashed run is retrieved.

    This occurs when a string is attached to the state instead of an exception or if
    the state's data is null.
    """

ExternalSignal

Bases: BaseException

Base type for external signal-like exceptions that should never be caught by users.

Source code in prefect/exceptions.py
302
303
304
305
class ExternalSignal(BaseException):
    """
    Base type for external signal-like exceptions that should never be caught by users.
    """

FailedRun

Bases: PrefectException

Raised when the result from a failed run is retrieved and an exception is not attached.

This occurs when a string is attached to the state instead of an exception or if the state's data is null.

Source code in prefect/exceptions.py
69
70
71
72
73
74
75
76
class FailedRun(PrefectException):
    """
    Raised when the result from a failed run is retrieved and an exception is not
    attached.

    This occurs when a string is attached to the state instead of an exception or if
    the state's data is null.
    """

FlowPauseTimeout

Bases: PrefectException

Raised when a flow pause times out

Source code in prefect/exceptions.py
400
401
class FlowPauseTimeout(PrefectException):
    """Raised when a flow pause times out"""

FlowRunWaitTimeout

Bases: PrefectException

Raised when a flow run takes longer than a given timeout

Source code in prefect/exceptions.py
404
405
class FlowRunWaitTimeout(PrefectException):
    """Raised when a flow run takes longer than a given timeout"""

FlowScriptError

Bases: PrefectException

Raised when a script errors during evaluation while attempting to load a flow.

Source code in prefect/exceptions.py
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
class FlowScriptError(PrefectException):
    """
    Raised when a script errors during evaluation while attempting to load a flow.
    """

    def __init__(
        self,
        user_exc: Exception,
        script_path: str,
    ) -> None:
        message = f"Flow script at {script_path!r} encountered an exception"
        super().__init__(message)

        self.user_exc = user_exc

    def rich_user_traceback(self, **kwargs):
        trace = Traceback.extract(
            type(self.user_exc),
            self.user_exc,
            self.user_exc.__traceback__.tb_next.tb_next.tb_next.tb_next,
        )
        return Traceback(trace, **kwargs)

InfrastructureError

Bases: PrefectException

A base class for exceptions related to infrastructure blocks

Source code in prefect/exceptions.py
376
377
378
379
class InfrastructureError(PrefectException):
    """
    A base class for exceptions related to infrastructure blocks
    """

InfrastructureNotAvailable

Bases: PrefectException

Raised when infrastructure is not accessible from the current machine. For example, if a process was spawned on another machine it cannot be managed.

Source code in prefect/exceptions.py
389
390
391
392
393
class InfrastructureNotAvailable(PrefectException):
    """
    Raised when infrastructure is not accessible from the current machine. For example,
    if a process was spawned on another machine it cannot be managed.
    """

InfrastructureNotFound

Bases: PrefectException

Raised when infrastructure is missing, likely because it has exited or been deleted.

Source code in prefect/exceptions.py
382
383
384
385
386
class InfrastructureNotFound(PrefectException):
    """
    Raised when infrastructure is missing, likely because it has exited or been
    deleted.
    """

InvalidNameError

Bases: PrefectException, ValueError

Raised when a name contains characters that are not permitted.

Source code in prefect/exceptions.py
272
273
274
275
class InvalidNameError(PrefectException, ValueError):
    """
    Raised when a name contains characters that are not permitted.
    """

InvalidRepositoryURLError

Bases: PrefectException

Raised when an incorrect URL is provided to a GitHub filesystem block.

Source code in prefect/exceptions.py
372
373
class InvalidRepositoryURLError(PrefectException):
    """Raised when an incorrect URL is provided to a GitHub filesystem block."""

MappingLengthMismatch

Bases: PrefectException

Raised when attempting to call Task.map with arguments of different lengths.

Source code in prefect/exceptions.py
348
349
350
351
class MappingLengthMismatch(PrefectException):
    """
    Raised when attempting to call Task.map with arguments of different lengths.
    """

MappingMissingIterable

Bases: PrefectException

Raised when attempting to call Task.map with all static arguments

Source code in prefect/exceptions.py
354
355
356
357
class MappingMissingIterable(PrefectException):
    """
    Raised when attempting to call Task.map with all static arguments
    """

MissingContextError

Bases: PrefectException, RuntimeError

Raised when a method is called that requires a task or flow run context to be active but one cannot be found.

Source code in prefect/exceptions.py
252
253
254
255
256
class MissingContextError(PrefectException, RuntimeError):
    """
    Raised when a method is called that requires a task or flow run context to be
    active but one cannot be found.
    """

MissingFlowError

Bases: PrefectException

Raised when a given flow name is not found in the expected script.

Source code in prefect/exceptions.py
107
108
109
110
class MissingFlowError(PrefectException):
    """
    Raised when a given flow name is not found in the expected script.
    """

MissingProfileError

Bases: PrefectException, ValueError

Raised when a profile name does not exist.

Source code in prefect/exceptions.py
259
260
261
262
class MissingProfileError(PrefectException, ValueError):
    """
    Raised when a profile name does not exist.
    """

MissingResult

Bases: PrefectException

Raised when a result is missing from a state; often when result persistence is disabled and the state is retrieved from the API.

Source code in prefect/exceptions.py
119
120
121
122
123
class MissingResult(PrefectException):
    """
    Raised when a result is missing from a state; often when result persistence is
    disabled and the state is retrieved from the API.
    """

NotPausedError

Bases: PrefectException

Raised when attempting to unpause a run that isn't paused.

Source code in prefect/exceptions.py
396
397
class NotPausedError(PrefectException):
    """Raised when attempting to unpause a run that isn't paused."""

ObjectAlreadyExists

Bases: PrefectException

Raised when the client receives a 409 (conflict) from the API.

Source code in prefect/exceptions.py
235
236
237
238
239
240
241
242
class ObjectAlreadyExists(PrefectException):
    """
    Raised when the client receives a 409 (conflict) from the API.
    """

    def __init__(self, http_exc: Exception, *args, **kwargs):
        self.http_exc = http_exc
        super().__init__(*args, **kwargs)

ObjectNotFound

Bases: PrefectException

Raised when the client receives a 404 (not found) from the API.

Source code in prefect/exceptions.py
225
226
227
228
229
230
231
232
class ObjectNotFound(PrefectException):
    """
    Raised when the client receives a 404 (not found) from the API.
    """

    def __init__(self, http_exc: Exception, *args, **kwargs):
        self.http_exc = http_exc
        super().__init__(*args, **kwargs)

ParameterBindError

Bases: TypeError, PrefectException

Raised when args and kwargs cannot be converted to parameters.

Source code in prefect/exceptions.py
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
class ParameterBindError(TypeError, PrefectException):
    """
    Raised when args and kwargs cannot be converted to parameters.
    """

    def __init__(self, msg: str):
        super().__init__(msg)

    @classmethod
    def from_bind_failure(
        cls, fn: Callable, exc: TypeError, call_args: List, call_kwargs: Dict
    ) -> Self:
        fn_signature = str(inspect.signature(fn)).strip("()")

        base = f"Error binding parameters for function '{fn.__name__}': {exc}"
        signature = f"Function '{fn.__name__}' has signature '{fn_signature}'"
        received = f"received args: {call_args} and kwargs: {list(call_kwargs.keys())}"
        msg = f"{base}.\n{signature} but {received}."
        return cls(msg)

ParameterTypeError

Bases: PrefectException

Raised when a parameter does not pass Pydantic type validation.

Source code in prefect/exceptions.py
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
class ParameterTypeError(PrefectException):
    """
    Raised when a parameter does not pass Pydantic type validation.
    """

    def __init__(self, msg: str):
        super().__init__(msg)

    @classmethod
    def from_validation_error(cls, exc: ValidationError) -> Self:
        bad_params = [
            f'{".".join(str(item) for item in err["loc"])}: {err["msg"]}'
            for err in exc.errors()
        ]
        msg = "Flow run received invalid parameters:\n - " + "\n - ".join(bad_params)
        return cls(msg)

Pause

Bases: PrefectSignal

Raised when a flow run is PAUSED and needs to exit for resubmission.

Source code in prefect/exceptions.py
292
293
294
295
296
297
298
299
class Pause(PrefectSignal):
    """
    Raised when a flow run is PAUSED and needs to exit for resubmission.
    """

    def __init__(self, *args, state=None, **kwargs):
        super().__init__(*args, **kwargs)
        self.state = state

PausedRun

Bases: PrefectException

Raised when the result from a paused run is retrieved.

Source code in prefect/exceptions.py
89
90
91
92
93
94
95
96
class PausedRun(PrefectException):
    """
    Raised when the result from a paused run is retrieved.
    """

    def __init__(self, *args, state=None, **kwargs):
        super().__init__(*args, **kwargs)
        self.state = state

PrefectException

Bases: Exception

Base exception type for Prefect errors.

Source code in prefect/exceptions.py
54
55
56
57
class PrefectException(Exception):
    """
    Base exception type for Prefect errors.
    """

PrefectHTTPStatusError

Bases: HTTPStatusError

Raised when client receives a Response that contains an HTTPStatusError.

Used to include API error details in the error messages that the client provides users.

Source code in prefect/exceptions.py
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
class PrefectHTTPStatusError(HTTPStatusError):
    """
    Raised when client receives a `Response` that contains an HTTPStatusError.

    Used to include API error details in the error messages that the client provides users.
    """

    @classmethod
    def from_httpx_error(cls: Type[Self], httpx_error: HTTPStatusError) -> Self:
        """
        Generate a `PrefectHTTPStatusError` from an `httpx.HTTPStatusError`.
        """
        try:
            details = httpx_error.response.json()
        except Exception:
            details = None

        error_message, *more_info = str(httpx_error).split("\n")

        if details:
            message_components = [error_message, f"Response: {details}", *more_info]
        else:
            message_components = [error_message, *more_info]

        new_message = "\n".join(message_components)

        return cls(
            new_message, request=httpx_error.request, response=httpx_error.response
        )

from_httpx_error classmethod

Generate a PrefectHTTPStatusError from an httpx.HTTPStatusError.

Source code in prefect/exceptions.py
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
@classmethod
def from_httpx_error(cls: Type[Self], httpx_error: HTTPStatusError) -> Self:
    """
    Generate a `PrefectHTTPStatusError` from an `httpx.HTTPStatusError`.
    """
    try:
        details = httpx_error.response.json()
    except Exception:
        details = None

    error_message, *more_info = str(httpx_error).split("\n")

    if details:
        message_components = [error_message, f"Response: {details}", *more_info]
    else:
        message_components = [error_message, *more_info]

    new_message = "\n".join(message_components)

    return cls(
        new_message, request=httpx_error.request, response=httpx_error.response
    )

PrefectSignal

Bases: BaseException

Base type for signal-like exceptions that should never be caught by users.

Source code in prefect/exceptions.py
278
279
280
281
class PrefectSignal(BaseException):
    """
    Base type for signal-like exceptions that should never be caught by users.
    """

ProtectedBlockError

Bases: PrefectException

Raised when an operation is prevented due to block protection.

Source code in prefect/exceptions.py
366
367
368
369
class ProtectedBlockError(PrefectException):
    """
    Raised when an operation is prevented due to block protection.
    """

ReservedArgumentError

Bases: PrefectException, TypeError

Raised when a function used with Prefect has an argument with a name that is reserved for a Prefect feature

Source code in prefect/exceptions.py
265
266
267
268
269
class ReservedArgumentError(PrefectException, TypeError):
    """
    Raised when a function used with Prefect has an argument with a name that is
    reserved for a Prefect feature
    """

ScriptError

Bases: PrefectException

Raised when a script errors during evaluation while attempting to load data

Source code in prefect/exceptions.py
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
class ScriptError(PrefectException):
    """
    Raised when a script errors during evaluation while attempting to load data
    """

    def __init__(
        self,
        user_exc: Exception,
        path: str,
    ) -> None:
        message = f"Script at {str(path)!r} encountered an exception: {user_exc!r}"
        super().__init__(message)
        self.user_exc = user_exc

        # Strip script run information from the traceback
        self.user_exc.__traceback__ = _trim_traceback(
            self.user_exc.__traceback__,
            remove_modules=[prefect.utilities.importtools],
        )

SignatureMismatchError

Bases: PrefectException, TypeError

Raised when parameters passed to a function do not match its signature.

Source code in prefect/exceptions.py
210
211
212
213
214
215
216
217
218
219
220
221
222
class SignatureMismatchError(PrefectException, TypeError):
    """Raised when parameters passed to a function do not match its signature."""

    def __init__(self, msg: str):
        super().__init__(msg)

    @classmethod
    def from_bad_params(cls, expected_params: List[str], provided_params: List[str]):
        msg = (
            f"Function expects parameters {expected_params} but was provided with"
            f" parameters {provided_params}"
        )
        return cls(msg)

TerminationSignal

Bases: ExternalSignal

Raised when a flow run receives a termination signal.

Source code in prefect/exceptions.py
308
309
310
311
312
313
314
class TerminationSignal(ExternalSignal):
    """
    Raised when a flow run receives a termination signal.
    """

    def __init__(self, signal: int):
        self.signal = signal

UnfinishedRun

Bases: PrefectException

Raised when the result from a run that is not finished is retrieved.

For example, if a run is in a SCHEDULED, PENDING, CANCELLING, or RUNNING state.

Source code in prefect/exceptions.py
 99
100
101
102
103
104
class UnfinishedRun(PrefectException):
    """
    Raised when the result from a run that is not finished is retrieved.

    For example, if a run is in a SCHEDULED, PENDING, CANCELLING, or RUNNING state.
    """

UnspecifiedFlowError

Bases: PrefectException

Raised when multiple flows are found in the expected script and no name is given.

Source code in prefect/exceptions.py
113
114
115
116
class UnspecifiedFlowError(PrefectException):
    """
    Raised when multiple flows are found in the expected script and no name is given.
    """

UpstreamTaskError

Bases: PrefectException

Raised when a task relies on the result of another task but that task is not 'COMPLETE'

Source code in prefect/exceptions.py
245
246
247
248
249
class UpstreamTaskError(PrefectException):
    """
    Raised when a task relies on the result of another task but that task is not
    'COMPLETE'
    """

exception_traceback

Convert an exception to a printable string with a traceback

Source code in prefect/exceptions.py
46
47
48
49
50
51
def exception_traceback(exc: Exception) -> str:
    """
    Convert an exception to a printable string with a traceback
    """
    tb = traceback.TracebackException.from_exception(exc)
    return "".join(list(tb.format()))