> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerix.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# iOS (Swift) — Error Tracking

> Report errors and automatically capture crashes from your native iOS app to the Lerix dashboard.

## Introduction

Lerix captures errors and crashes from your native iOS app so you can debug issues faster. After you complete the [iOS installation](/frameworks/ios/installation), use `Lerix.throwError` to send custom errors or caught exceptions to your dashboard — uncaught crashes are captured automatically, with no extra code required.

<Note>
  Make sure you have initialized the SDK with `Lerix.initialize()` before reporting errors.
</Note>

## Report an error

Use `Lerix.throwError` to manually report an error. This is useful when you catch an error yourself and want to send it to Lerix with extra context.

```swift theme={"dark"}
do {
    try riskyOperation()
} catch {
    Lerix.throwError(
        "\(error)",
        stack: Thread.callStackSymbols,
        type: .runtimeError,
        severity: .high,
        metadata: ["userId": "123", "action": "payment", "amount": 100]
    )
}
```

### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `issue` | `String` | Yes | Error message or description |
| `stack` | `[String]` | No | Stack trace frames — pass `Thread.callStackSymbols` for the current call stack |
| `type` | `BugType` | No | Bug classification (default: `.runtimeError`) |
| `severity` | `BugSeverity` | No | Severity level (default: `.medium`) |
| `metadata` | `[String: Any]?` | No | Additional context to attach to the report |

### `BugType` values

| Value | Description |
| - | - |
| `runtimeError` | An unhandled exception thrown at runtime |
| `logicBug` | Incorrect behavior that doesn't throw |
| `uiBug` | A visual or layout defect |
| `networkError` | A failed or malformed network request |
| `performance` | Slowness, jank, or excessive resource use |
| `compatibility` | Breaks on a specific device, OS version, or platform |
| `validationError` | Invalid input passed validation it shouldn't have |
| `security` | A security-relevant defect |
| `crash` | The app terminated unexpectedly |
| `unknown` | None of the above |

### `BugSeverity` values

| Value | Description |
| - | - |
| `critical` | Blocks core functionality or affects all users |
| `high` | Serious impact, but a workaround exists |
| `medium` | Noticeable but limited impact |
| `low` | Minor or cosmetic |
| `unknown` | Severity not yet assessed |

## Automatic crash capture

`Lerix.initialize()` installs a crash handler by default, covering both:

* **Uncaught exceptions** (`NSException` — e.g. an unimplemented selector, an invalid collection operation).
* **Fatal signals** (`SIGABRT`, `SIGILL`, `SIGSEGV`, `SIGFPE`, `SIGBUS`, `SIGTRAP`) — this is what catches typical Swift runtime traps: force-unwrapping `nil`, an array index out of range, a failed `precondition`, and similar.

A crash can't reliably make a network call — the process is already terminating — so the report is written to disk synchronously at crash time, then sent automatically the *next* time your app launches, tagged `type: .crash, severity: .critical`. You don't need to do anything to receive it; it shows up in the dashboard on the following launch.

To disable it (e.g. if your app already has its own crash reporter and you only want manual `throwError` calls):

```swift theme={"dark"}
Lerix.initialize(
    apiKey: "your-api-key",
    projectId: "your-project-id",
    enableCrashReporting: false
)
```

<Note>
  Stack traces are symbolicated using the app's own debug symbols at the time of the crash, so a Release build with symbols stripped may show addresses instead of function names for some frames — this is a normal characteristic of native crash reporting, not a bug in the SDK.
</Note>

### Verify the integration

Throw a test error to confirm everything is working:

```swift theme={"dark"}
Lerix.throwError("Test error", stack: Thread.callStackSymbols)
```

Then open your [dashboard](https://app.lerix.dev) — the error should appear within seconds.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.