MLServe.Error exception (MLServe v0.1.3)

The structured error MLServe raises and reports.

Every non-bang MLServe function returns {:error, reason} where reason is a plain atom or tagged tuple, as documented on MLServe.predict/3. This struct is the raised form: bang functions such as MLServe.predict!/3 convert the reason with wrap/2 and raise it.

It is an exception, so raise, Exception.message/1 and rescue MLServe.Error all work:

iex> MLServe.Error.wrap(:model_not_found, model: :fraud) |> Exception.message()
"model :fraud is not loaded"

Fields

:type — the machine-readable classification, e.g. :model_not_found, :timeout
:message — human-readable description
:code — optional short code carried through from a backend
:details — optional map of context (model name, version, limits)

Summary

Types

t()

type()

Machine-readable error classification.

Functions

new(type, message, opts \\ [])

Builds an error struct.

retryable?(reason)

Returns true when retrying the same call could plausibly succeed.

wrap(reason, details \\ [])

Converts an {:error, reason} reason term into an MLServe.Error.

Types

t()

@type t() :: %MLServe.Error{
  __exception__: true,
  code: String.t() | nil,
  details: map() | nil,
  message: String.t(),
  type: type()
}

type()

@type type() ::
  :model_not_found
  | :model_not_ready
  | :timeout
  | :overloaded
  | :invalid_input
  | :batch_too_large
  | :load_failed
  | :backend_error
  | :config
  | :unknown

Machine-readable error classification.

Functions

new(type, message, opts \\ [])

@spec new(type(), String.t(), keyword()) :: t()

Builds an error struct.

Parameters

type: the classification atom
message: human-readable description
opts: :code and :details

Examples

iex> err = MLServe.Error.new(:timeout, "inference timed out", details: %{model: :fraud})
iex> err.type
:timeout

retryable?(reason)

@spec retryable?(t() | MLServe.BackendError.t() | term()) :: boolean()

Returns true when retrying the same call could plausibly succeed.

Transient conditions — a timeout, a full queue, a model still loading — are retryable. A missing model, invalid input, or a backend that raised are not: retrying re-runs the same failure.

This is what the Oban guide uses to choose between :snooze and :discard.

Examples

iex> MLServe.Error.retryable?(MLServe.Error.wrap(:timeout))
true

iex> MLServe.Error.retryable?(MLServe.Error.wrap({:invalid_input, "bad"}))
false

wrap(reason, details \\ [])

@spec wrap(
  term(),
  keyword()
) :: t() | MLServe.BackendError.t()

Converts an {:error, reason} reason term into an MLServe.Error.

Used by the bang functions. details are merged into the resulting struct so the raised message can name the model and version that failed.

Parameters

reason: the reason term from a non-bang MLServe function
details: keyword list of context, typically model: and version:

Examples

iex> MLServe.Error.wrap(:model_not_ready, model: :fraud).type
:model_not_ready

iex> MLServe.Error.wrap({:invalid_input, "amount must be a number"}) |> Exception.message()
"invalid input: amount must be a number"