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

This exception represents command execution errors. For example, the cache
cannot perform a command because it has not started, it does not exist, or
the adapter failed to perform it for any reason.

## Exception fields

See `t:t/0`.

## Error reasons

The `:reason` field can assume the following values:

  * `:timeout` - if there is a timeout when executing the cache command.

  * `:transaction_aborted` - if a transaction execution fails and aborts.

  * `:event_listener_already_exists` - if another cache entry listener with
    the same ID already exists.

  * `:event_listener_error` - if a cache entry event listener fails when
    processing an event.

  * `t:Exception.t/0` - if the underlying adapter fails due to an exception.

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

# `reason`

```elixir
@type reason() :: atom() | {atom(), any()} | Exception.t()
```

Error reason type

# `t`

```elixir
@type t() :: %Nebulex.Error{
  __exception__: true,
  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 it is present, it
    invokes `module.format_error(reason, metadata)` to format the error
    reason. The argument `metadata` is a keyword with the metadata given
    to the exception. See `format_error/2` for more information.

  * `:metadata` - the metadata contains the options given to the
    exception excluding the `:reason` and `:module` that are part
    of the exception fields. For example, when raising an exception
    `raise Nebulex.Error, reason: :test, foo: :bar`, the metadata
    will be `[foo: :bar]`.

# `format_error`

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

A callback invoked when a custom formatter module is provided.

## 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*