Implementation:Bentoml BentoML Exceptions

Knowledge Sources	Bentoml_BentoML
Domains	Core Framework, Error Handling
Last Updated	2026-02-13 15:00 GMT

Overview

Defines the complete exception hierarchy for BentoML, mapping custom exception types to HTTP status codes for consistent error handling across the framework.

Description

This module provides the BentoMLException base class which all BentoML-specific exceptions derive from. Each exception class carries an error_code attribute mapped to an HTTPStatus value, enabling automatic HTTP response code generation in API servers. The base class maintains an error_mapping class-level dictionary that auto-registers subclasses via __init_subclass__. Key exception classes include:

• InvalidArgument (400 Bad Request) -- for bad CLI arguments, HTTP requests, or API parameters
• BadInput (400) -- specifically for bad API server input
• NotFound (404) -- for missing resources
• UnprocessableEntity (422) -- for unprocessable requests
• ServiceUnavailable (503) -- for capacity overload
• InternalServerError (500) -- for errors in user code (runners/services)
• RemoteException -- wraps exceptions from remote servers with an optional payload
• StateException and its subclasses UnservableException and ServerStateException -- for invalid object/server states
• MissingDependencyException -- for missing optional dependencies
• BentoMLConfigException -- for configuration errors
• CLIException -- for CLI issues
• CloudRESTApiClientError -- for cloud API errors
• ImportServiceError -- for service import failures
• APIDeprecated -- for deprecated API usage

Usage

Use these exception classes throughout BentoML code to raise appropriate errors with correct HTTP status codes. The exception hierarchy enables catch-all handling via BentoMLException or fine-grained handling of specific error types.

Code Reference

Source Location

• Repository: Bentoml_BentoML
• File: src/bentoml/exceptions.py
• Lines: 1-141

Signature

class BentoMLException(Exception):
    error_code = HTTPStatus.INTERNAL_SERVER_ERROR
    error_mapping: dict[HTTPStatus, type[BentoMLException]] = {}
    def __init__(self, message: str, *, error_code: HTTPStatus | None = None): ...

class StateException(Exception):
    error_code = HTTPStatus.BAD_REQUEST

class RemoteException(BentoMLException):
    def __init__(self, message: str, payload: BentoMLException | None = None): ...

class InvalidArgument(BentoMLException):       # 400
class InternalServerError(BentoMLException):   # 500
class APIDeprecated(BentoMLException):         # 500
class BadInput(InvalidArgument):               # 400
class NotFound(BentoMLException):              # 404
class UnprocessableEntity(BentoMLException):   # 422
class ServiceUnavailable(BentoMLException):    # 503
class BentoMLConfigException(BentoMLException):
class MissingDependencyException(BentoMLException):
class CLIException(BentoMLException):
class CloudRESTApiClientError(BentoMLException):
class ImportServiceError(BentoMLException):
class UnservableException(StateException):
class ServerStateException(StateException):

Import

from bentoml.exceptions import BentoMLException, NotFound, InvalidArgument
from bentoml.exceptions import MissingDependencyException, CLIException

I/O Contract

Inputs

Name	Type	Required	Description
message	str	Yes	Human-readable error description
error_code	HTTPStatus or None	No	Override the default HTTP status code for this exception instance
payload	BentoMLException or None	No	Original exception from remote server (RemoteException only)

Outputs

Name	Type	Description
exception	BentoMLException subclass	Raised exception instance with message and error_code attributes

Usage Examples

from bentoml.exceptions import NotFound, InvalidArgument, MissingDependencyException

# Raise when a resource is not found
raise NotFound("Model 'my_model:v1' not found in store")

# Raise for invalid user input
raise InvalidArgument("Parameter 'batch_size' must be a positive integer")

# Raise for missing optional dependency
raise MissingDependencyException(
    "'tensorflow' is required for this runner. Install with: pip install tensorflow"
)

# Catch BentoML errors generically
from bentoml.exceptions import BentoMLException
try:
    result = some_operation()
except BentoMLException as e:
    print(f"Error ({e.error_code}): {e.message}")

Related Pages

• Implementation:Bentoml_BentoML_Store_Base
• Implementation:Bentoml_BentoML_InferenceAPI