# `ALLM.Error.StreamError`
[🔗](https://github.com/cykod/ALLM/blob/v0.3.0/lib/allm/error/stream_error.ex#L1)

Errors that surface mid-stream.

Layer A — serializable. Typically wraps an underlying `%AdapterError{}` via
the `:cause` field (`:reason` is `:adapter_error`) or carries the malformed
term for `:malformed_event`.

See Phase 1 design §Sub-phase 1.1 for the closed reason enum.

# `reason`

```elixir
@type reason() :: :adapter_error | :cancelled | :timeout | :malformed_event | :unknown
```

Closed set of streaming-specific error reasons (spec §20).

# `t`

```elixir
@type t() :: %ALLM.Error.StreamError{
  __exception__: true,
  cause: term() | nil,
  event_index: non_neg_integer() | nil,
  message: String.t(),
  metadata: map(),
  provider: atom() | nil,
  reason: reason()
}
```

# `new`

```elixir
@spec new(
  reason(),
  keyword()
) :: t()
```

Build a `%StreamError{}` from a `reason` atom and optional keyword fields.

`opts` may include `:message`, `:provider`, `:event_index`, `:cause`, and
`:metadata`. When `:message` is omitted, the default is
`"stream error: #{reason}"`.

Raises `ArgumentError` if `reason` is not one of the atoms in the closed
`t:reason/0` enum.

## Examples

    iex> err = ALLM.Error.StreamError.new(:cancelled)
    iex> err.reason
    :cancelled
    iex> Exception.message(err)
    "stream error: cancelled"

    iex> err = ALLM.Error.StreamError.new(:adapter_error, event_index: 3)
    iex> err.event_index
    3

---

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