# `Nebulex.Error`
[🔗](https://github.com/elixir-nebulex/nebulex/blob/v3.1.0/lib/nebulex/exceptions.ex#L1)

Raised, or returned in an `{:error, _}` tuple, when a command fails. For
example, the adapter could not run it, it timed out, or a transaction was
aborted.

## Exception fields

See `t:t/0`.

## Error reasons

The `:reason` field can be one of:

  * `:timeout` - the command timed out.

  * `:transaction_aborted` - a transaction failed and was aborted.

  * `:event_listener_already_exists` - another cache entry listener with
    the same ID is already registered.

  * `:event_listener_error` - a cache entry event listener failed while
    processing an event.

  * `t:Exception.t/0` - the adapter raised an exception.

  * `t:any/0` - the command failed with an adapter-specific error.

# `reason`

```elixir
@type reason() :: any()
```

Error reason type.

Usually an atom, a `{atom, term}` tuple, or an exception, but adapters may
use any term.

# `t`

```elixir
@type t() :: %Nebulex.Error{
  __exception__: term(),
  metadata: keyword(),
  module: module(),
  reason: reason()
}
```

The type for this exception struct.

This exception has the following public fields:

  * `:reason` - the error reason. It can be one of the Nebulex-specific
    reasons described in the ["Error reasons"](#module-error-reasons)
    section in the module documentation.

  * `:module` - a custom error formatter module. When present, the
    message is built with `module.format_error(reason, metadata)`, where
    `metadata` is the keyword list given to the exception. See
    `format_error/2`.

  * `:metadata` - the options given to the exception, minus `:reason` and
    `:module`. For example, `raise Nebulex.Error, reason: :test, foo: :bar`
    gives the metadata `[foo: :bar]`.

# `format_error`

```elixir
@spec format_error(any(), keyword()) :: binary()
```

Formats the error message. A custom formatter module (see the `:module`
field) must define a function with the same name and arguments.

## Arguments

  * `reason` - the error reason.
  * `metadata` - a keyword with the metadata given to the exception.

For example, if an adapter returns:

    wrap_error Nebulex.Error,
      reason: :my_reason,
      module: MyAdapter.Formatter,
      foo: :bar

the exception invokes:

    MyAdapter.Formatter.format_error(:my_reason, foo: :bar)

# `maybe_format_metadata`

```elixir
@spec maybe_format_metadata(binary(), keyword()) :: binary()
```

Formats the error metadata when not empty.

---

*Consult [api-reference.md](api-reference.md) for complete listing*