Principle:Mlflow Mlflow Error Handling and Exception Hierarchy

Knowledge Sources	Mlflow_Mlflow
Domains	Error Handling, API Design, Exception Hierarchy
Last Updated	2026-02-13 20:00 GMT

Overview

A structured exception hierarchy that maps domain-specific error codes to HTTP status codes, enabling consistent error serialization across REST API boundaries.

Description

The error handling system provides a layered exception hierarchy rooted in a single base exception class. This base class carries three pieces of information: a human-readable message, a machine-readable error code drawn from a protobuf-defined enumeration, and optional additional key-value metadata. Every exception in the hierarchy can serialize itself to JSON for transmission over HTTP, and can resolve its own HTTP status code from a bidirectional mapping between error codes and HTTP statuses.

The hierarchy is organized into several tiers:

Base exception is the root of all platform-specific exceptions. It accepts a message, an error code (defaulting to an internal error), and optional keyword arguments. It normalizes the error code to its string name, falling back to the internal error code if the provided code is unrecognized. It provides methods for JSON serialization and HTTP status code resolution. A convenience class method allows constructing instances with a specific error code (such as invalid parameter value) without requiring callers to import the error code constants directly.

REST exception is thrown when a non-success response is received from a remote API call. It is constructed from a JSON response body and attempts to resolve the error code through multiple strategies: first by looking up the code name directly in the protobuf enumeration, then by treating it as a numeric HTTP status and mapping it to the corresponding error code, and finally falling back to the default internal error if neither strategy succeeds. This class overrides the pickle reduction method to ensure it can be serialized across process boundaries.

Domain-specific exceptions cover particular failure modes:

• Execution exception for project execution failures.
• Missing configuration exception for absent configuration files or directories.
• Invalid URL exception for malformed request URLs.
• Unsupported multipart upload exception for artifact repositories that do not support chunked uploads.
• Not implemented exception for features that have not yet been built.

Tracing exceptions form a sub-hierarchy designed to be non-blocking. Since tracing logic should not interrupt the main application flow, these exceptions are distinguished by type so that callers can catch and suppress them appropriately. The tracing sub-hierarchy includes:

• A general tracing exception base.
• A trace data exception that contextualizes errors with either a request identifier or an artifact path, and produces distinct messages for "not found" versus "corrupted data" cases.
• Specialized leaf classes for trace data not found and trace data corrupted scenarios.

Error code to HTTP status mapping is maintained as two dictionaries: one mapping error code names to HTTP status codes, and a reverse mapping from HTTP statuses back to error code names. When multiple error codes map to the same HTTP status (for example, several 400-level codes), the reverse mapping explicitly chooses a canonical error code for each status. A helper function resolves an HTTP status integer to its corresponding error code enum value.

Usage

This principle applies when:

• Building a REST API that must return structured, machine-readable error responses.
• Multiple error conditions must map to appropriate HTTP status codes.
• Exceptions need to cross process boundaries (via pickling) or network boundaries (via JSON serialization).
• Certain categories of errors (such as tracing) should be non-fatal and handled differently from critical errors.
• Client code must reconstruct error information from API responses.

Theoretical Basis

The error handling system relies on a bidirectional error code mapping with hierarchical exception dispatch:

ERROR CODE RESOLUTION (outbound, exception to HTTP response):
  1. Exception is raised with an error_code enum value
  2. error_code is normalized to its string name via the protobuf enum
     - If normalization fails, fall back to INTERNAL_ERROR
  3. HTTP status is looked up from ERROR_CODE_TO_HTTP_STATUS map
     - If not found, default to 500

ERROR CODE RESOLUTION (inbound, HTTP response to exception):
  1. JSON response body is parsed for "error_code" field
  2. Attempt to resolve as a protobuf enum name
  3. If that fails, attempt to parse as integer HTTP status code
     and map via HTTP_STATUS_TO_ERROR_CODE
  4. If that also fails, log a warning and default to INTERNAL_ERROR

JSON SERIALIZATION:
  serialize(exception) -> {"error_code": string, "message": string, ...extra_kwargs}

EXCEPTION HIERARCHY:
  Exception
    MlflowException (base: message + error_code + kwargs)
      RestException (constructed from JSON response)
      ExecutionException
      MissingConfigException
      InvalidUrlException
      _UnsupportedMultipartUploadException
      MlflowNotImplementedException
      MlflowTracingException (non-blocking tracing errors)
        MlflowTraceDataException (contextual: request_id or artifact_path)
          MlflowTraceDataNotFound
          MlflowTraceDataCorrupted

The key design principles are:

• Single responsibility per exception class: Each exception class represents a distinct failure domain, enabling targeted catch clauses.
• Graceful degradation: Error code resolution always falls back to a safe default rather than raising secondary errors.
• Serialization completeness: Every exception can round-trip through JSON (for network transmission) and pickle (for multiprocessing), preserving all diagnostic information.
• Non-blocking tracing errors: The tracing sub-hierarchy allows instrumentation failures to be caught and logged without disrupting the primary application workflow.

Related Pages

• Implementation:Mlflow_Mlflow_Exceptions