Windows Error Reporting

Sentry and Windows Error Reporting (WER) can be used together on Windows. This guide documents how to share data between them.

WER Compatibility

WER behavior depends on the configured Native SDK backend. The table below shows whether each backend captures SEH and fast-fail crashes in Sentry and whether WER can continue its own report processing.

For more information about choosing a backend, see Backend Tradeoffs.

WER Integration

The Native SDK comes with an optional backend-independent WER integration that registers Sentry tags and attachments with WER. Include the integration when configuring the Native SDK; the following example uses the most WER-compatible native backend:

cmake -B build \
  -D SENTRY_BACKEND=native \
  -D SENTRY_INTEGRATION_WER=ON

cmake -B build \
  -D SENTRY_BACKEND=native \
  -D SENTRY_INTEGRATION_WER=ON

The WER integration is automatically initialized by the Native SDK. Use the regular Sentry APIs to register tags and attachments. For example:

sentry_set_tag("channel", "stable");
sentry_attach_file("C:\\logs\\app.log");

sentry_set_tag("channel", "stable");
sentry_attach_file("C:\\logs\\app.log");

The integration maps common Sentry APIs to their WER equivalents where possible:

Each WER registration is best effort. Values that are incompatible, too long, or too large are skipped. WER also applies its own registration limits, such as WER_MAX_REGISTERED_METADATA (8) and WER_MAX_REGISTERED_ENTRIES (512).

Custom metadata requires Windows 10 version 1703 or later, or Windows Server 2016 or later. On earlier versions, tag registration is skipped.

Unlike Sentry attachments, WER files and memory blocks aren't always included in every report. WER includes them only when its reporting service requests additional data. Buffer attachments are included only in heap or larger dumps, not in minidumps or smaller dumps.

WER Migration

Existing WER users can configure and upload local dumps to Sentry while keeping WER responsible for collection. In this guide, the Native SDK only acts as the uploader to make the same dumps also available in Sentry.

Configure WER to Collect Local Dumps

WER can be configured to store a minidump to a local directory when a process crashes. This requires setting registry keys under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\Windows Error Reporting\LocalDumps, which needs administrator privileges and is typically done at installation time.

The following registry configuration enables local dump collection for your application:

For example, you could deploy this from an installer by running:

reg add "HKLM\SOFTWARE\Microsoft\Windows\Windows Error Reporting\LocalDumps\YourApp.exe" /v DumpFolder /t REG_EXPAND_SZ /d "%%LOCALAPPDATA%%\YourApp\CrashDumps" /f
reg add "HKLM\SOFTWARE\Microsoft\Windows\Windows Error Reporting\LocalDumps\YourApp.exe" /v DumpType /t REG_DWORD /d 1 /f
reg add "HKLM\SOFTWARE\Microsoft\Windows\Windows Error Reporting\LocalDumps\YourApp.exe" /v DumpCount /t REG_DWORD /d 10 /f

reg add "HKLM\SOFTWARE\Microsoft\Windows\Windows Error Reporting\LocalDumps\YourApp.exe" /v DumpFolder /t REG_EXPAND_SZ /d "%%LOCALAPPDATA%%\YourApp\CrashDumps" /f
reg add "HKLM\SOFTWARE\Microsoft\Windows\Windows Error Reporting\LocalDumps\YourApp.exe" /v DumpType /t REG_DWORD /d 1 /f
reg add "HKLM\SOFTWARE\Microsoft\Windows\Windows Error Reporting\LocalDumps\YourApp.exe" /v DumpCount /t REG_DWORD /d 10 /f

reg add "HKLM\SOFTWARE\Microsoft\Windows\Windows Error Reporting\LocalDumps\YourApp.exe" /v DumpFolder /t REG_EXPAND_SZ /d "%LOCALAPPDATA%\YourApp\CrashDumps" /f
reg add "HKLM\SOFTWARE\Microsoft\Windows\Windows Error Reporting\LocalDumps\YourApp.exe" /v DumpType /t REG_DWORD /d 1 /f
reg add "HKLM\SOFTWARE\Microsoft\Windows\Windows Error Reporting\LocalDumps\YourApp.exe" /v DumpCount /t REG_DWORD /d 10 /f

For more details, see Collecting User-Mode Dumps.

Build the Native SDK with Crash Reporting Disabled

To prevent the Native SDK from capturing crashes (which would result in duplicate crash reports alongside WER), build it without a crash backend:

cmake -DSENTRY_BACKEND=none ...

cmake -DSENTRY_BACKEND=none ...

With SENTRY_BACKEND=none, the SDK will not capture crashes on its own, but you can still use its API to send minidumps and have your crashes stored and processed in Sentry.

Capture and Send WER Dumps to Sentry

On application startup, initialize the SDK and upload any minidumps WER has stored in the dump directory. For each minidump file, call sentry_capture_minidumpw() with its path:

sentry_options_t *options = sentry_options_new();
sentry_options_set_dsn(options, "___PUBLIC_DSN___");
sentry_init(options);

/* for each minidump_path in L"%LOCALAPPDATA%\\YourApp\\CrashDumps" */ {
    sentry_uuid_t event_id = sentry_capture_minidumpw(minidump_path);
    if (!sentry_uuid_is_nil(&event_id)) {
        DeleteFileW(minidump_path);
    }
}
sentry_close();

sentry_options_t *options = sentry_options_new();
sentry_options_set_dsn(options, "___PUBLIC_DSN___");
sentry_init(options);

/* for each minidump_path in L"%LOCALAPPDATA%\\YourApp\\CrashDumps" */ {
    sentry_uuid_t event_id = sentry_capture_minidumpw(minidump_path);
    if (!sentry_uuid_is_nil(&event_id)) {
        DeleteFileW(minidump_path);
    }
}
sentry_close();

sentry_capture_minidumpw() processes the minidump and uploads it to Sentry as a crash event.