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

# Errors and crashes

> Send game errors as events, see crash-free sessions and players, and find the errors that happen most.

Errors and crashes are events, as in GameAnalytics and PostHog. An error goes into the same table as your other events, with the same player, session, build and platform. So you can use errors in funnels, retention, filters and charts. For example:

* Do players from one campaign crash more often?
* Did the error rate go up after build 572?
* Do players who get an error in level 3 stop playing?

> [!NOTE]
>
> ManaLens does not store native crash dumps or symbols. For native crashes (a segfault in the engine or in a GDExtension), keep Sentry or Backtrace. ManaLens still counts these crashes, with `app_unclean_exit`.

## The events

| Event | When | Properties |
| - | - | - |
| `error` | `track_error()` (Godot) or `TrackError()` (Unity), or a captured engine error: Godot 4.5+ engine and script errors, Unity exceptions, `Debug.LogError` and failed asserts | See below |
| `app_unclean_exit` | At the next launch, when the last run did not exit normally while the game had focus | `previous_session_id`, `previous_build`, `previous_app_version` |

`app_unclean_exit` has the session ID and the time of the run that crashed, so it counts in that session and that build. A game that the operating system closed in the background is not counted. A normal quit (with or without `shutdown()`) is not counted.

Properties of `error`:

| Property | Meaning |
| - | - |
| `severity` | `debug`, `info`, `warning`, `error` or `critical` |
| `message` | The error text, at most 1024 characters |
| `error_type` | The error class, for example `SaveFailed`. Godot engine errors use `engine_error`, `script_error` or `engine_warning`. Unity uses the exception class (for example `NullReferenceException`), `log_error`, `assert` or `log_warning`. |
| `handled` | `false` when the game could not recover. Engine errors are always `false`. |
| `source` | `manual` (`track_error()` or `TrackError()`), `godot_logger` (Godot engine capture) or `unity_log` (Unity log capture) |
| `fingerprint` | The group key. Errors with the same fingerprint are one row in **Top errors**. |
| `file`, `line`, `function` | Where the error happened, when known |
| `stack` | The script stack trace, at most 1024 characters |
| `breadcrumbs` | The last 20 event names before the error, separated by commas |
| `engine_error_type` | Godot engine capture only: `error`, `script` or `warning` |
| `log_type` | Unity log capture only: `exception`, `error`, `assert` or `warning` |

## Send errors from Godot

```gdscript theme={null}
UntitledAnalytics.track_error("Save failed for slot %d" % slot, {
    "error_type": "SaveFailed",
    "severity": "critical",
    "handled": false,
    "properties": {"level": level},
})
```

On Godot 4.5 and later, the SDK also sends engine and script errors (for example `push_error()`, a call on a null instance, or a failed `load()`). It uses `OS.add_logger()`. Set `capture_engine_errors` to `false` to turn it off. Warnings are off by default (`capture_warnings`). In release exports, script stack traces need the project setting `debug/settings/gdscript/always_track_call_stacks`.

On Godot before 4.5, use `track_error()`. The crash event works on every version.

## Send errors from Unity

```csharp theme={null}
UntitledAnalytics.TrackError($"Save failed for slot {slot}", new TrackErrorOptions
{
    ErrorType = "SaveFailed",
    Severity = "critical",
    Handled = false,
    Properties = new Dictionary<string, object> { ["level"] = level },
});

catch (Exception e) { UntitledAnalytics.TrackError(e); }
```

The [Unity SDK](https://docs.manalens.dev/sdks/unity.md) also sends unhandled exceptions, `Debug.LogError` and failed asserts, from any thread (`Application.logMessageReceivedThreaded`). Set `CaptureErrors` to `false` to turn it off. Warnings are off by default (`CaptureWarnings`).

### Grouping

By default the fingerprint is a hash of `error_type`, `file` and `function`. The line number is not in it, so an edit above the error keeps the group. Without a file or function, the hash uses the message with numbers and quoted text removed: `Save failed for slot 3` and `Save failed for slot 4` are one group. Set `fingerprint` in `track_error()` to group in your own way.

### Limits

| Limit | Value |
| - | - |
| Same fingerprint | Once a second |
| All errors | 20 in 10 seconds |
| Engine errors | 5 in one frame, 50 in one session (`max_auto_errors_per_session`) |

`track_error()` calls do not count toward the session limit. The SDK adds the number of dropped errors to the next `session_end` as `errors_dropped`.

### Remove personal data

```gdscript theme={null}
UntitledAnalytics.set_before_send(func(props: Dictionary):
    if String(props.message).contains("@"):
        return null  # drop the error
    props.erase("stack")
    return props)
```

The function gets the properties of each `error` event. Return the properties to send, or `null` to drop the error.

## Game health board

Open **Dashboards**, click the **Game health** template under **Templates**, then click **Create board**. It has:

* **Crash-free sessions:** 1 minus the share of sessions with `app_unclean_exit` or a `critical` error with `handled` = `false`.
* **Crash-free players:** the same, with distinct players.
* **Errored sessions:** the share of sessions with an `error` or `critical` error. Warnings do not count.
* **Errors per session** and **Errors per session by build**.
* **Top errors:** one row for each fingerprint, with the latest message, count, players, first and last time seen in the date range, and the latest build.

The board reads game events: client events with `context.app`, from a native build or from a browser game that sets the [web SDK `app` option](https://docs.manalens.dev/sdks/web#app-context). These are SQL charts, so you can edit them in the chart editor. Rates over date ranges of different lengths are not comparable: a longer range has more sessions for each player.

## Other engines

Any engine can send `error` and `app_unclean_exit` to the [events endpoint](https://docs.manalens.dev/sdks/app-events.md). Use the same property names, so the Game health board works.


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