# modal.exception

Modal-specific exception types.

## Notes on `grpclib.GRPCError` migration

Historically, the Modal SDK could propagate `grpclib.GRPCError` exceptions out
to user code.  As of v1.3, we are in the process of gracefully migrating to
always raising a Modal exception type in these cases. To avoid breaking user
code that relies on catching `grpclib.GRPCError`, a subset of Modal exception
types temporarily inherit from `grpclib.GRPCError`.

We encourage users to migrate any code that currently catches `grpclib.GRPCError`
to instead catch the appropriate Modal exception type. The following mapping
between GRPCError status codes and Modal exception types is currently in use:

```
CANCELLED -> ServiceError
UNKNOWN -> ServiceError
INVALID_ARGUMENT -> InvalidError
DEADLINE_EXCEEDED -> ServiceError
NOT_FOUND -> NotFoundError
ALREADY_EXISTS -> AlreadyExistsError
PERMISSION_DENIED -> PermissionDeniedError
RESOURCE_EXHAUSTED -> ResourceExhaustedError
FAILED_PRECONDITION -> ConflictError
ABORTED -> ConflictError
OUT_OF_RANGE -> InvalidError
UNIMPLEMENTED -> UnimplementedError
INTERNAL -> InternalError
UNAVAILABLE -> ServiceError
DATA_LOSS -> DataLossError
UNAUTHENTICATED -> AuthError
```

## modal.exception.AlreadyExistsError

```python
class AlreadyExistsError(modal.exception.Error, modal.exception._GRPCErrorWrapper)
```

Raised when a resource creation conflicts with an existing resource.

```python
def __init__(self, message: Optional[str] = None):
    # Override GRPCError's init and repr to behave more like a regular Exception
    # (We don't customize these anywhere in our custom error types currently).
```

### message

```python
@property
def message(self) -> str:
```

### status

```python
@property
def status(self) -> grpclib.Status:
```

### details

```python
@property
def details(self) -> Any:
```

## modal.exception.AsyncUsageWarning

```python
class AsyncUsageWarning(UserWarning)
```

Warning emitted when a blocking Modal interface is used in an async context.

## modal.exception.AuthError

```python
class AuthError(modal.exception.Error, modal.exception._GRPCErrorWrapper)
```

Raised when a client has missing or invalid authentication.

```python
def __init__(self, message: Optional[str] = None):
    # Override GRPCError's init and repr to behave more like a regular Exception
    # (We don't customize these anywhere in our custom error types currently).
```

### message

```python
@property
def message(self) -> str:
```

### status

```python
@property
def status(self) -> grpclib.Status:
```

### details

```python
@property
def details(self) -> Any:
```

## modal.exception.ClientClosed

```python
class ClientClosed(modal.exception.Error)
```

## modal.exception.ConflictError

```python
class ConflictError(modal.exception.InvalidError, modal.exception._GRPCErrorWrapper)
```

Raised when a resource conflict occurs between the request and current system state.

```python
def __init__(self, message: Optional[str] = None):
    # Override GRPCError's init and repr to behave more like a regular Exception
    # (We don't customize these anywhere in our custom error types currently).
```

### message

```python
@property
def message(self) -> str:
```

### status

```python
@property
def status(self) -> grpclib.Status:
```

### details

```python
@property
def details(self) -> Any:
```

## modal.exception.ConnectionError

```python
class ConnectionError(modal.exception.Error)
```

Raised when an issue occurs while connecting to the Modal servers.

## modal.exception.DataLossError

```python
class DataLossError(modal.exception.Error, modal.exception._GRPCErrorWrapper)
```

Raised when data is lost or corrupted.

```python
def __init__(self, message: Optional[str] = None):
    # Override GRPCError's init and repr to behave more like a regular Exception
    # (We don't customize these anywhere in our custom error types currently).
```

### message

```python
@property
def message(self) -> str:
```

### status

```python
@property
def status(self) -> grpclib.Status:
```

### details

```python
@property
def details(self) -> Any:
```

## modal.exception.DeprecationError

```python
class DeprecationError(UserWarning)
```

UserWarning category emitted when a deprecated Modal feature or API is used.

## modal.exception.DeserializationError

```python
class DeserializationError(modal.exception.Error)
```

Raised to provide more context when an error is encountered during deserialization.

## modal.exception.ExecTimeoutError

```python
class ExecTimeoutError(modal.exception.TimeoutError)
```

Raised when a container process exceeds its execution duration limit and times out.

## modal.exception.ExecutionError

```python
class ExecutionError(modal.exception.Error)
```

Raised when something unexpected happened during runtime.

## modal.exception.FilesystemExecutionError

```python
class FilesystemExecutionError(modal.exception.Error)
```

Raised when an unknown error is thrown during a container filesystem operation.

## modal.exception.FunctionTimeoutError

```python
class FunctionTimeoutError(modal.exception.TimeoutError)
```

Raised when a Function exceeds its execution duration limit and times out.

## modal.exception.InputCancellation

```python
class InputCancellation(BaseException)
```

Raised when the current input is cancelled by the task

Intentionally a BaseException instead of an Exception, so it won't get
caught by unspecified user exception clauses that might be used for retries and
other control flow.

## modal.exception.InteractiveTimeoutError

```python
class InteractiveTimeoutError(modal.exception.TimeoutError)
```

Raised when interactive frontends time out while trying to connect to a container.

## modal.exception.InternalError

```python
class InternalError(modal.exception.Error, modal.exception._GRPCErrorWrapper)
```

Raised when an internal error occurs in the Modal system.

```python
def __init__(self, message: Optional[str] = None):
    # Override GRPCError's init and repr to behave more like a regular Exception
    # (We don't customize these anywhere in our custom error types currently).
```

### message

```python
@property
def message(self) -> str:
```

### status

```python
@property
def status(self) -> grpclib.Status:
```

### details

```python
@property
def details(self) -> Any:
```

## modal.exception.InternalFailure

```python
class InternalFailure(modal.exception.Error)
```

Retriable internal error.

## modal.exception.InvalidError

```python
class InvalidError(modal.exception.Error, modal.exception._GRPCErrorWrapper)
```

Raised when user does something invalid.

```python
def __init__(self, message: Optional[str] = None):
    # Override GRPCError's init and repr to behave more like a regular Exception
    # (We don't customize these anywhere in our custom error types currently).
```

### message

```python
@property
def message(self) -> str:
```

### status

```python
@property
def status(self) -> grpclib.Status:
```

### details

```python
@property
def details(self) -> Any:
```

## modal.exception.ModuleNotMountable

```python
class ModuleNotMountable(Exception)
```

## modal.exception.MountUploadTimeoutError

```python
class MountUploadTimeoutError(modal.exception.TimeoutError)
```

Raised when a Mount upload times out.

## modal.exception.NotFoundError

```python
class NotFoundError(modal.exception.Error, modal.exception._GRPCErrorWrapper)
```

Raised when a requested resource was not found.

```python
def __init__(self, message: Optional[str] = None):
    # Override GRPCError's init and repr to behave more like a regular Exception
    # (We don't customize these anywhere in our custom error types currently).
```

### message

```python
@property
def message(self) -> str:
```

### status

```python
@property
def status(self) -> grpclib.Status:
```

### details

```python
@property
def details(self) -> Any:
```

## modal.exception.OutputExpiredError

```python
class OutputExpiredError(modal.exception.TimeoutError)
```

Raised when the Output exceeds expiration and times out.

## modal.exception.PendingDeprecationError

```python
class PendingDeprecationError(UserWarning)
```

Soon to be deprecated feature. Only used intermittently because of multi-repo concerns.

## modal.exception.PermissionDeniedError

```python
class PermissionDeniedError(modal.exception.Error, modal.exception._GRPCErrorWrapper)
```

Raised when a user does not have permission to perform the requested operation.

```python
def __init__(self, message: Optional[str] = None):
    # Override GRPCError's init and repr to behave more like a regular Exception
    # (We don't customize these anywhere in our custom error types currently).
```

### message

```python
@property
def message(self) -> str:
```

### status

```python
@property
def status(self) -> grpclib.Status:
```

### details

```python
@property
def details(self) -> Any:
```

## modal.exception.RemoteError

```python
class RemoteError(modal.exception.Error)
```

Raised when an error occurs on the Modal server.

## modal.exception.RequestSizeError

```python
class RequestSizeError(modal.exception.Error)
```

Raised when an operation produces a gRPC request that is rejected by the server for being too large.

## modal.exception.ResourceExhaustedError

```python
class ResourceExhaustedError(modal.exception.Error, modal.exception._GRPCErrorWrapper)
```

Raised when a server-side resource has been exhausted, e.g. a quota or rate limit.

```python
def __init__(self, message: Optional[str] = None):
    # Override GRPCError's init and repr to behave more like a regular Exception
    # (We don't customize these anywhere in our custom error types currently).
```

### message

```python
@property
def message(self) -> str:
```

### status

```python
@property
def status(self) -> grpclib.Status:
```

### details

```python
@property
def details(self) -> Any:
```

## modal.exception.SandboxTerminatedError

```python
class SandboxTerminatedError(modal.exception.Error)
```

Raised when a Sandbox is terminated for an internal reason.

## modal.exception.SandboxTimeoutError

```python
class SandboxTimeoutError(modal.exception.TimeoutError)
```

Raised when a Sandbox exceeds its execution duration limit and times out.

## modal.exception.SerializationError

```python
class SerializationError(modal.exception.Error)
```

Raised to provide more context when an error is encountered during serialization.

## modal.exception.ServerWarning

```python
class ServerWarning(UserWarning)
```

Warning originating from the Modal server and re-issued in client code.

## modal.exception.ServiceError

```python
class ServiceError(modal.exception.Error, modal.exception._GRPCErrorWrapper)
```

Raised when an error occurs in basic client/server communication.

```python
def __init__(self, message: Optional[str] = None):
    # Override GRPCError's init and repr to behave more like a regular Exception
    # (We don't customize these anywhere in our custom error types currently).
```

### message

```python
@property
def message(self) -> str:
```

### status

```python
@property
def status(self) -> grpclib.Status:
```

### details

```python
@property
def details(self) -> Any:
```

## modal.exception.TimeoutError

```python
class TimeoutError(modal.exception.Error)
```

Base class for Modal timeouts.

## modal.exception.UnimplementedError

```python
class UnimplementedError(modal.exception.Error, modal.exception._GRPCErrorWrapper)
```

Raised when a requested operation is not implemented or not supported.

```python
def __init__(self, message: Optional[str] = None):
    # Override GRPCError's init and repr to behave more like a regular Exception
    # (We don't customize these anywhere in our custom error types currently).
```

### message

```python
@property
def message(self) -> str:
```

### status

```python
@property
def status(self) -> grpclib.Status:
```

### details

```python
@property
def details(self) -> Any:
```

## modal.exception.VersionError

```python
class VersionError(modal.exception.Error)
```

Raised when the current client version of Modal is unsupported.

## modal.exception.VolumeUploadTimeoutError

```python
class VolumeUploadTimeoutError(modal.exception.TimeoutError)
```

Raised when a Volume upload times out.

## modal.exception.simulate_preemption

```python
def simulate_preemption(wait_seconds: int, jitter_seconds: int = 0):
```

Utility for simulating a preemption interrupt after `wait_seconds` seconds.
The first interrupt is the SIGINT signal. After 30 seconds, a second
interrupt will trigger.

This second interrupt simulates SIGKILL, and should not be caught.
Optionally add between zero and `jitter_seconds` seconds of additional waiting before first interrupt.

**Usage:**

```python notest
import time
from modal.exception import simulate_preemption

simulate_preemption(3)

try:
    time.sleep(4)
except KeyboardInterrupt:
    print("got preempted") # Handle interrupt
    raise
```

See https://modal.com/docs/guide/preemption for more details on preemption
handling.