Implementation:Mlflow Mlflow Exceptions

Knowledge Sources	Mlflow_Mlflow
Domains	Error Handling, Core Infrastructure
Last Updated	2026-02-13 20:00 GMT

Overview

Defines the MLflow exception hierarchy, error code enumeration, and bidirectional mappings between protobuf error codes and HTTP status codes used across the entire MLflow codebase.

Description

mlflow/exceptions.py provides the core error handling infrastructure for MLflow. It establishes a mapping between protobuf-defined ErrorCode values (imported from mlflow.protos.databricks_pb2) and HTTP status codes via two dictionaries:

• ERROR_CODE_TO_HTTP_STATUS: Maps error code names (e.g., "INTERNAL_ERROR") to HTTP status codes (e.g., 500). This is used when serializing exceptions for HTTP responses.
• HTTP_STATUS_TO_ERROR_CODE: The reverse mapping from HTTP status codes to error code names. Ambiguous mappings (where multiple error codes map to the same HTTP status) are resolved by choosing canonical defaults: 400 maps to BAD_REQUEST, 404 maps to ENDPOINT_NOT_FOUND, 500 maps to INTERNAL_ERROR.

The module defines the following exception classes:

• MlflowException: The base exception class for all MLflow errors. It stores an error_code (defaulting to INTERNAL_ERROR), a message, and optional json_kwargs for additional serialization fields. It provides serialize_as_json() for HTTP response formatting and get_http_status_code() for status code lookup. It also includes the invalid_parameter_value() class method factory.

• RestException: Extends MlflowException for non-200 REST API responses. It accepts a JSON dictionary, extracts the error code and message, and handles multiple error code formats including string error codes, protobuf error codes, and numeric HTTP status codes. It overrides __reduce__ to support pickling.

• ExecutionException: For project execution failures.
• MissingConfigException: For missing configuration files or directories.
• InvalidUrlException: For invalid URL errors during HTTP requests.
• _UnsupportedMultipartUploadException: Internal exception for unsupported multipart uploads (NOT_IMPLEMENTED).
• MlflowTracingException: Base for tracing-related errors that should not block main execution.
• MlflowTraceDataException: For trace data errors, with context from request_id or artifact_path.
• MlflowTraceDataNotFound: Specialized exception when trace data is not found.
• MlflowTraceDataCorrupted: Specialized exception when trace data is corrupted.
• MlflowNotImplementedException: For unimplemented features.

The helper function get_error_code() converts an HTTP status code to its corresponding protobuf ErrorCode integer value.

Usage

Use MlflowException and its subclasses throughout the MLflow codebase to raise structured errors that can be serialized to JSON for HTTP responses. Use RestException when handling non-200 responses from REST API calls.

Code Reference

Source Location

• Repository: Mlflow_Mlflow
• File: mlflow/exceptions.py
• Lines: 1-219

Signature

ERROR_CODE_TO_HTTP_STATUS: dict[str, int]
HTTP_STATUS_TO_ERROR_CODE: dict[int, str]

def get_error_code(http_status) -> int: ...

class MlflowException(Exception):
    def __init__(self, message, error_code=INTERNAL_ERROR, **kwargs): ...
    def serialize_as_json(self) -> str: ...
    def get_http_status_code(self) -> int: ...
    @classmethod
    def invalid_parameter_value(cls, message, **kwargs) -> "MlflowException": ...

class RestException(MlflowException):
    def __init__(self, json: dict): ...
    def __reduce__(self): ...

class ExecutionException(MlflowException): ...
class MissingConfigException(MlflowException): ...
class InvalidUrlException(MlflowException): ...
class _UnsupportedMultipartUploadException(MlflowException): ...
class MlflowTracingException(MlflowException): ...
class MlflowTraceDataException(MlflowTracingException): ...
class MlflowTraceDataNotFound(MlflowTraceDataException): ...
class MlflowTraceDataCorrupted(MlflowTraceDataException): ...
class MlflowNotImplementedException(MlflowException): ...

Import

from mlflow.exceptions import MlflowException, RestException
from mlflow.protos.databricks_pb2 import INVALID_PARAMETER_VALUE, RESOURCE_DOES_NOT_EXIST

I/O Contract

Inputs (MlflowException)

Name	Type	Required	Description
message	str or Exception	Yes	The error message or exception describing what went wrong
error_code	int	No	A protobuf ErrorCode value (default: INTERNAL_ERROR)
**kwargs	dict	No	Additional key-value pairs included in JSON serialization

Inputs (RestException)

Name	Type	Required	Description
json	dict	Yes	A dictionary containing "error_code" and optionally "message" from a REST response

Outputs

Name	Type	Description
serialize_as_json()	str	JSON string with "error_code", "message", and any additional kwargs
get_http_status_code()	int	HTTP status code corresponding to the error code (default: 500)

Error Code Mapping

Error Code	HTTP Status
INTERNAL_ERROR, INVALID_STATE, DATA_LOSS	500
NOT_IMPLEMENTED	501
TEMPORARILY_UNAVAILABLE	503
DEADLINE_EXCEEDED	504
REQUEST_LIMIT_EXCEEDED, RESOURCE_EXHAUSTED	429
CANCELLED	499
ABORTED, RESOURCE_CONFLICT, ALREADY_EXISTS	409
NOT_FOUND, ENDPOINT_NOT_FOUND, RESOURCE_DOES_NOT_EXIST	404
PERMISSION_DENIED	403
CUSTOMER_UNAUTHORIZED, UNAUTHENTICATED	401
BAD_REQUEST, RESOURCE_ALREADY_EXISTS, INVALID_PARAMETER_VALUE	400

Usage Examples

Raising an Exception

from mlflow.exceptions import MlflowException
from mlflow.protos.databricks_pb2 import RESOURCE_DOES_NOT_EXIST

raise MlflowException(
    "Experiment with ID '123' not found",
    error_code=RESOURCE_DOES_NOT_EXIST
)

Using the Factory Method

from mlflow.exceptions import MlflowException

raise MlflowException.invalid_parameter_value(
    "Parameter 'max_results' must be a positive integer"
)

Handling REST Errors

from mlflow.exceptions import RestException

try:
    response = make_api_call()
except RestException as e:
    print(f"API error: {e.error_code} - {e.message}")
    print(f"HTTP status: {e.get_http_status_code()}")

Exception Hierarchy

Exception
  MlflowException
    RestException
    ExecutionException
    MissingConfigException
    InvalidUrlException
    _UnsupportedMultipartUploadException
    MlflowTracingException
      MlflowTraceDataException
        MlflowTraceDataNotFound
        MlflowTraceDataCorrupted
    MlflowNotImplementedException

Related Pages

• Environment:Mlflow_Mlflow_Python_Runtime_Environment