# `Ambient.Error`
[🔗](https://github.com/mariuszzak/ambient/blob/v0.2.0/lib/ambient/error.ex#L1)

The exception every Ambient misuse raises, carrying a machine-readable
`:reason` alongside the human-readable message.

Match on `:reason` rather than on message text – the wording is not part of
the contract:

    try do
      Ambient.ProcessOverride.put(table, :k, :v)
    rescue
      e in Ambient.Error ->
        case e.reason do
          :overrides_disabled -> :skip
          :server_not_started -> start_and_retry()
        end
    end

## Reasons

  * `:overrides_disabled` – the build didn't opt into the override machinery
    (`config :ambient, enable_overrides: …`). See `Ambient.ProcessOverride`.
  * `:server_not_started` – no `Ambient.ProcessOverride.Server` owns this
    table; call `Ambient.start_servers/1` first.
  * `{:not_shared_owner, pid}` – the table is in shared mode and only `pid`
    may write to it.
  * `:cant_allow_in_shared_mode` – `allow/3` is meaningless while a table is
    shared, since every process already reads the shared owner's values.
  * `:not_a_value_module` – something that is neither a module built with
    `Ambient.Value` nor a table atom
    was passed to `Ambient.start_servers/1` and friends.
  * `{:server_start_failed, reason}` – the supervisor refused to start a
    table's server.

# `reason`

```elixir
@type reason() ::
  :overrides_disabled
  | :server_not_started
  | {:not_shared_owner, pid()}
  | :cant_allow_in_shared_mode
  | :not_a_value_module
  | {:server_start_failed, term()}
```

# `t`

```elixir
@type t() :: %Ambient.Error{
  __exception__: term(),
  message: String.t(),
  reason: reason(),
  table: atom() | nil
}
```

---

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