Minidumps and Native Crashes

A segmentation fault, access violation, or abort can terminate an application before it can send a normal exception. A native crash reporter deals with that failure outside the crashing code and writes a minidump: a compact binary record of the process at the time of the crash.

Bugsink turns that minidump into an issue with the crashing thread, the other thread stacks, loaded modules, crash reason, operating system, and CPU architecture.

The dump contains instruction addresses, but not the source code needed to explain them. Your build therefore uploads the matching debug information separately. Bugsink joins both sides by debug ID and resolves those addresses to function names, filenames, line numbers, and source context.

This is similar to sourcemaps for JavaScript: the application sends the crash, while the build pipeline supplies the information needed to make its stacktrace readable.

Minidumps require Bugsink 2.6.2 or newer. Hosted Bugsink has the feature enabled. Self-hosted installations must enable FEATURE_MINIDUMPS until it becomes the default in Bugsink 2.7.

How the pieces fit

The names around native crash reporting are easy to mix up because they describe different parts of the same path:

  • Crashpad and Breakpad are crash handlers. They catch native crashes and write minidumps. Crashpad also includes a persistent report database and an uploader; Breakpad applications commonly provide their own upload callback.
  • sentry-native is an SDK for C and C++. It adds tags, breadcrumbs, and other event context, and can use Crashpad, Breakpad, or its own native crash backend underneath.
  • Electron and several game or cross-platform SDKs wrap a native crash handler. Whether they work depends on the backend and upload format they use, not merely on the SDK having “native” in its feature list.
  • Debug files belong to the build. Depending on the platform these are usually an ELF debug companion, a PDB, a dSYM, or a Breakpad .sym file. They are not sent by the crashing application.
  • sentry-cli uploads the debug files. Bugsink implements the debug-file upload endpoints it uses.

You do not need to replace a working crash handler just to use Bugsink. The dump itself is not tied to C or C++: Rust, Zig, and other native applications can use the same path. The useful question is what their crash handler uploads.

Supported upload formats

Bugsink 2.6.2 accepts a minidump in either of these forms:

  • A multipart request to the project’s /minidump/ endpoint, with the dump in the upload_file_minidump field.
  • A Sentry envelope containing an attachment whose attachment_type is event.minidump. The envelope may also contain an event with tags, breadcrumbs, release information, and other context.

This covers both upload styles used by sentry-native: its Crashpad backend sends directly to the minidump endpoint, while its Breakpad backend sends the dump as an envelope attachment.

The complete Crashpad path has been tested with sentry-native 0.17.4 on Linux x86-64. The envelope path is covered by Bugsink’s integration tests, but I have not yet tested every SDK and platform combination end to end.

Existing crash reporters

If your application already uses sentry-native, start by replacing its DSN with the DSN from the Bugsink project’s SDK Setup page. Keep the SDK’s persistent database and crash-handler configuration: those are client-side concerns and do not change when Bugsink becomes the receiver.

If your application uses Crashpad directly, configure its upload URL as:

https://bugsink.example/api/PROJECT-ID/minidump/?sentry_key=PROJECT-KEY

An existing Breakpad integration can upload the .dmp from its crash callback to the same endpoint. The request must be multipart form data and use upload_file_minidump as the field name.

If another tool already leaves you with a .dmp, the same endpoint also works as a simple uploader:

curl --fail-with-body \
  -F upload_file_minidump=@crash.dmp \
  'https://bugsink.example/api/42/minidump/?sentry_key=YOUR-PROJECT-KEY'

The project ID and key are the two project-specific values in its DSN.

Framework SDKs

Several SDKs use the same building blocks, but that does not make them one interchangeable integration.

  • Electron: the current Electron SDK stores Crashpad dumps and sends them in an event.minidump envelope. Bugsink accepts that protocol. I have inspected the SDK path, but have not yet run a packaged Electron application against Bugsink. Native Electron or Node modules also need their matching debug files; Bugsink does not fetch Electron’s own symbols from an external symbol server.
  • Rust: the sentry-minidump crate captures crashes on Linux, macOS, and Windows and sends the dump as an event.minidump attachment. That is an accepted Bugsink upload path; the crate itself has not yet been tested end to end against Bugsink.
  • Unreal Engine: the Windows and Linux SDK backends build on sentry-native and use Crashpad by default. That makes their minidump transport a plausible match, but this is not yet an end-to-end tested Bugsink integration. Unreal’s separate CrashReportClient format is not the minidump endpoint documented here.
  • Unity, Godot, Flutter, .NET, and Android: their SDKs can use sentry-native on some targets, but each platform chooses its own backend. A managed exception, Android tombstone, or Apple crash report is not automatically a minidump. Treat these as platform-specific integrations until the exact crash backend has been verified.

In other words, compatibility is strongest when you can identify either the direct minidump request or the event.minidump envelope in the SDK’s debug log.

Upload debug files

The minidump identifies every loaded module by a debug ID. Bugsink can only resolve a module when the exact debug file with that ID has already been uploaded to the same project.

Open Tokens in Bugsink and create a token with:

  • Project: the project receiving the crashes.
  • Capability: only debug-files:upload.
  • Description: a name that identifies the build job.

Then upload your build’s debug files before distributing it:

export SENTRY_AUTH_TOKEN=your-bugsink-token

sentry-cli --url https://bugsink.example \
  debug-files upload \
  --org bugsink \
  --project your-project-slug \
  --include-sources \
  --wait \
  path/to/debug-files

Use the Bugsink project slug for --project. Bugsink has no organizations, so --org is only a compatibility placeholder.

--include-sources creates a separate source bundle for context lines. Keep the exact debug files for every build that is still in use: a rebuild from the same source can produce different debug IDs.

On Linux, upload separate .debug companions rather than the executable itself.

Enable minidumps

For Docker, add this to the Bugsink service and recreate the container:

environment:
  FEATURE_MINIDUMPS: "true"

For a virtualenv installation, add the setting to the BUGSINK dictionary in bugsink_conf.py:

BUGSINK = {
    # your existing settings...
    "FEATURE_MINIDUMPS": True,
}

Restart Bugsink after changing it. On a non-Docker installation, restart both the webserver and the Snappea worker.

Limitations

  • Only sentry-native with Crashpad on Linux x86-64 has been tested end to end. The parser and upload path understand native PDB, Mach-O/dSYM, and Breakpad symbol formats, but the complete Windows, macOS, and framework-SDK flows have not yet been verified against Bugsink.
  • Symbolication happens during ingestion. Uploading a missing debug file later does not improve existing events.
  • Apple crash reports and Unreal crash archives are not minidumps. Support for those formats does not follow from accepting dSYMs or the minidumps embedded in some other crash format.
  • Local variables are not extracted. Full dumps can contain more memory than the default SDK minidump, but Bugsink does not currently turn that memory into local variables.
  • Inlined calls are not expanded into separate frames. Bugsink currently uses the first symbolication result for an instruction.
  • The original dump is not retained for download. Bugsink removes the temporary .dmp after processing it. Complete envelope retention is a separate ingestion-debugging setting.
  • Uploads and source files have size limits. MAX_ATTACHMENT_SIZE and MAX_ENVELOPE_SIZE both default to 100 MiB; the limits apply after request decompression. A source file larger than MAX_SOURCE_CONTEXT_FILE_SIZE—10 MiB by default—is omitted while its stack frame is kept.

Treat minidumps and debug files as sensitive data. Dumps contain process memory and can include application data; source bundles contain your source code. The resulting event follows the project’s normal retention rules.

Troubleshooting

No event arrives

Enable the SDK or crash handler’s debug log and inspect the upload response.

  • 404: minidumps are probably not enabled.
  • 403: the project ID and project key do not belong together.
  • 413: the request or envelope is over its configured size limit.

If you are testing Bugsink from a source checkout, put it behind Gunicorn. Crashpad uses chunked transfer encoding, which Django’s development server does not handle.

Stacktrace has raw addresses

Open the event’s JSON view and find the module in debug_meta.images. Compare its debug_id with the output of:

sentry-cli debug-files check path/to/debug-file

Different IDs mean the dump and debug file came from different builds. Matching IDs with raw frames usually mean the wrong kind of object was uploaded, or that the debug file arrived after the event. Upload the file first and send a new crash.

Source context is missing

Make sure the upload used --include-sources. The source paths recorded by the compiler must still exist on the machine running sentry-cli, and each source file must fit within MAX_SOURCE_CONTEXT_FILE_SIZE.

Library frames are missing

Each executable and shared library has its own debug ID. Upload the matching debug file for every first-party module whose frames you want Bugsink to resolve.

Debug-file upload fails

Run sentry-cli with --log-level=debug and keep --wait. Its output should distinguish authentication or project scope problems from invalid and oversized debug files.

Further reading