---
title: exceptions
sidebarTitle: exceptions
---

# `prefect.exceptions`



Prefect-specific exceptions.


## Functions

### `exception_traceback` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L48" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
exception_traceback(exc: Exception) -> str
```


Convert an exception to a printable string with a traceback


## Classes

### `PrefectException` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L56" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Base exception type for Prefect errors.


### `CrashedRun` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L62" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


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.


### `FailedRun` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L71" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


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.


### `CancelledRun` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L81" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


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.


### `PausedRun` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L91" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Raised when the result from a paused run is retrieved.


### `UnfinishedRun` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L103" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


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.


### `MissingFlowError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L111" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


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


### `UnspecifiedFlowError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L117" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


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


### `MissingResult` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L123" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


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


### `ScriptError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L130" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


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


### `ParameterTypeError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L153" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Raised when a parameter does not pass Pydantic type validation.


**Methods:**

#### `from_validation_error` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L162" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_validation_error(cls, exc: ValidationError) -> Self
```

### `ParameterBindError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L171" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Raised when args and kwargs cannot be converted to parameters.


**Methods:**

#### `from_bind_failure` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L180" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_bind_failure(cls, fn: Callable[..., Any], exc: TypeError, call_args: tuple[Any, ...], call_kwargs: dict[str, Any]) -> Self
```

### `SignatureMismatchError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L196" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


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


**Methods:**

#### `from_bad_params` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L203" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_bad_params(cls, expected_params: list[str], provided_params: list[str]) -> Self
```

### `ObjectNotFound` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L213" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


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


### `ObjectAlreadyExists` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L233" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


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


### `ObjectLimitReached` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L243" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Raised when the client receives a 403 (forbidden) from the API due to reaching an object limit (e.g. maximum number of deployments).


### `ObjectUnsupported` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L253" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Raised when the client receives a 403 (forbidden) from the API due to an unsupported object (i.e. requires a specific Prefect Cloud tier).


### `UpstreamTaskError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L263" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


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


### `MissingContextError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L270" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


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


### `MissingProfileError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L277" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Raised when a profile name does not exist.


### `ReservedArgumentError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L283" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


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


### `InvalidNameError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L290" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Raised when a name contains characters that are not permitted.


### `PrefectSignal` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L296" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


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


### `Abort` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L302" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


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

Indicates that the run should exit immediately.


### `Pause` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L310" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


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


### `ExternalSignal` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L322" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


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


### `TerminationSignal` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L328" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Raised when a flow run receives a termination signal.


### `PrefectHTTPStatusError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L337" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


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.


**Methods:**

#### `from_httpx_error` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L345" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
from_httpx_error(cls: type[Self], httpx_error: HTTPStatusError) -> Self
```

Generate a `PrefectHTTPStatusError` from an `httpx.HTTPStatusError`.


### `MappingLengthMismatch` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L368" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


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


### `MappingMissingIterable` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L374" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


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


### `BlockMissingCapabilities` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L380" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


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


### `ProtectedBlockError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L386" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Raised when an operation is prevented due to block protection.


### `InvalidRepositoryURLError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L392" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


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


### `InfrastructureError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L396" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


A base class for exceptions related to infrastructure blocks


### `InfrastructureNotFound` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L402" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


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


### `InfrastructureNotAvailable` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L409" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


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


### `NotPausedError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L416" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


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


### `FlowPauseTimeout` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L420" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Raised when a flow pause times out


### `FlowRunWaitTimeout` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L424" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Raised when a flow run takes longer than a given timeout


### `PrefectImportError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L428" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


An error raised when a Prefect object cannot be imported due to a move or removal.


### `SerializationError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L437" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Raised when an object cannot be serialized.


### `ConfigurationError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L443" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Raised when a configuration is invalid.


### `EventTooLarge` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L449" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Raised when an event exceeds the configured maximum size.


### `ProfileSettingsValidationError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L460" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Raised when a profile settings are invalid.


### `HashError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/exceptions.py#L469" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Raised when hashing objects fails

