# `Kreuzberg.Error`
[🔗](https://github.com/kreuzberg-dev/kreuzberg/blob/main/lib/kreuzberg/error.ex#L1)

Exception module for Kreuzberg extraction errors.

Defines error types and provides standardized error handling for all
extraction and configuration-related failures in the Kreuzberg library.

## Error Types

All errors inherit from this exception and include:

  * `:message` - Human-readable error description
  * `:reason` - Categorized error reason (atom)
  * `:context` - Optional additional context about the error

## Exceptions

  * `Kreuzberg.Error` - Base exception for all Kreuzberg errors

## Examples

    iex> raise Kreuzberg.Error, message: "Invalid PDF", reason: :invalid_format
    ** (Kreuzberg.Error) Invalid PDF

    iex> try do
    ...>   raise Kreuzberg.Error, message: "OCR failed", reason: :ocr_error
    ...> rescue
    ...>   e in Kreuzberg.Error ->
    ...>     {e.message, e.reason}
    ...> end
    {"OCR failed", :ocr_error}

# `reason`

```elixir
@type reason() ::
  :invalid_format
  | :invalid_config
  | :ocr_error
  | :extraction_error
  | :io_error
  | :embedding_error
  | :nif_error
  | :unknown_error
```

# `t`

```elixir
@type t() :: %Kreuzberg.Error{
  __exception__: true,
  context: map() | nil,
  message: String.t() | nil,
  reason: atom() | nil
}
```

# `new`

```elixir
@spec new(String.t(), reason(), map() | nil) :: t()
```

Creates a new Kreuzberg error.

## Parameters

  * `message` - The error message (defaults to reason atom string)
  * `reason` - The error reason (atom categorizing the error type)
  * `context` - Optional map with additional error context

## Returns

An exception struct that can be raised.

## Examples

    iex> error = Kreuzberg.Error.new("File not found", :io_error)
    iex> error.message
    "File not found"
    iex> error.reason
    :io_error

    iex> error = Kreuzberg.Error.new(
    ...>   "Unsupported format",
    ...>   :invalid_format,
    ...>   %{"format" => "xyz", "supported" => ["pdf", "docx"]}
    ...> )
    iex> error.context
    %{"format" => "xyz", "supported" => ["pdf", "docx"]}

# `to_string`

```elixir
@spec to_string(t()) :: String.t()
```

Converts an error to a descriptive string representation.

Includes the message and reason, with context details if available.

## Parameters

  * `error` - A Kreuzberg.Error struct

## Returns

A formatted error string.

## Examples

    iex> error = Kreuzberg.Error.new("Failed to extract", :extraction_error)
    iex> Kreuzberg.Error.to_string(error)
    "Failed to extract (extraction_error)"

    iex> error = Kreuzberg.Error.new(
    ...>   "Invalid format",
    ...>   :invalid_format,
    ...>   %{"details" => "unsupported"}
    ...> )
    iex> Kreuzberg.Error.to_string(error)
    "Invalid format (invalid_format) - context: %{\"details\" => \"unsupported\"}"

---

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