Connect a native application to Bugsink

A native process can terminate before it has a chance to report an ordinary error. sentry-native uses Crashpad as a separate crash handler, which writes a minidump and sends it after your application has stopped.

This guide connects a C or C++ application, uploads the debug information from its build, and triggers a deliberate crash. You will finish with a readable application frame and source context in Bugsink, rather than raw instruction addresses.

To follow along, create a Bugsink project and copy its DSN. The quickstart guide shows where to find it. You also need a project token with only debug-files:upload, which the build will use to upload symbols. Hosted Bugsink has minidumps enabled. On a self-hosted Bugsink installation before 2.7, set FEATURE_MINIDUMPS=True and restart the web process and background worker.

Start with the application

The example is a small inventory command. Before adding crash reporting, build it and exercise both its successful lookup and its ordinary missing-product error:

cmake -S . -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo
cmake --build build --parallel
build/inventory coffee
test "$(build/inventory missing-product 2>&1 || test $? -eq 1)" = \
    "Product missing-product is not in inventory"
rm -rf build

The following steps add the SDK and turn that same missing-product path into the deliberate crash used to verify Crashpad.

Build sentry-native with Crashpad

The open-source Sentry Native SDK provides the Crashpad integration which can send crashes to Bugsink. It is a CMake project with Git submodules. This Linux example pins sentry-native 0.17.6 and builds a static SDK:

git clone --branch 0.17.6 --depth 1 --recurse-submodules --shallow-submodules \
    https://github.com/getsentry/sentry-native.git .vendor/sentry-native
cmake -S .vendor/sentry-native -B .vendor/sentry-native-build \
    -DCMAKE_BUILD_TYPE=RelWithDebInfo \
    -DSENTRY_BACKEND=crashpad \
    -DSENTRY_BUILD_SHARED_LIBS=OFF \
    -DSENTRY_BUILD_EXAMPLES=OFF \
    -DSENTRY_BUILD_TESTS=OFF
cmake --build .vendor/sentry-native-build --parallel
cmake --install .vendor/sentry-native-build \
    --prefix "$PWD/.vendor/sentry-native-install"

The install contains the sentry library and headers, plus bin/crashpad_handler. Ship the handler with your application; it is not a Bugsink service.

Find the installed CMake package, link sentry::sentry, and copy crashpad_handler next to the application executable. sentry-native looks there by default:

cmake_minimum_required(VERSION 3.24)
project(bugsink_native_crash C CXX)

set(SENTRY_NATIVE_ROOT "" CACHE PATH "Installed sentry-native prefix")
if(NOT SENTRY_NATIVE_ROOT)
    message(FATAL_ERROR "Configure with -DSENTRY_NATIVE_ROOT=/path/to/sentry-native/install")
endif()

list(PREPEND CMAKE_PREFIX_PATH "${SENTRY_NATIVE_ROOT}")
find_package(sentry CONFIG REQUIRED)
find_program(
    CRASHPAD_HANDLER
    crashpad_handler
    PATHS "${SENTRY_NATIVE_ROOT}/bin"
    NO_DEFAULT_PATH
    REQUIRED
)

add_executable(native-crash main.c)
target_compile_features(native-crash PRIVATE c_std_11)
target_compile_options(native-crash PRIVATE -Wall -Wextra -Wpedantic)
if(CMAKE_C_COMPILER_ID STREQUAL "GNU")
    target_compile_options(native-crash PRIVATE -fno-reorder-blocks-and-partition)
endif()
target_link_libraries(native-crash PRIVATE sentry::sentry)
set_target_properties(native-crash PROPERTIES LINKER_LANGUAGE CXX)

add_custom_command(
    TARGET native-crash
    POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E copy_if_different
            "${CRASHPAD_HANDLER}"
            "$<TARGET_FILE_DIR:native-crash>/crashpad_handler"
)

The sample disables one GCC code-layout optimization so its tiny crash function keeps a clear name in the demonstration stack. That option is not a requirement for Bugsink.

Initialize the SDK

Initialize the SDK early in application startup. The DSN comes from the environment, while the database path gives the separate handler a durable place to keep reports if an upload is interrupted:

sentry_options_t *options = sentry_options_new();
sentry_options_set_dsn(options, dsn);
sentry_options_set_database_path(options, cache);
sentry_options_set_release(options, "inventory-native@1.0.0");
sentry_options_set_debug(options, getenv("SENTRY_DEBUG") != NULL);
if (sentry_init(options) != 0) {
    fputs("sentry-native could not initialize Crashpad\n", stderr);
    return 2;
}

Use a writable, persistent cache location appropriate for your application. For example, a desktop application could use its per-user application-data directory. The handler path can likewise be set explicitly with sentry_options_set_handler_path() when it is not next to the executable.

Build the application against the installed SDK and confirm that both executables are present:

cmake -S . -B build \
    -DCMAKE_BUILD_TYPE=RelWithDebInfo \
    -DSENTRY_NATIVE_ROOT="$PWD/.vendor/sentry-native-install"
cmake --build build --parallel
test -x build/native-crash
test -x build/crashpad_handler

Upload debug information

A minidump contains module addresses and debug IDs, but not enough information to recover your function names and source lines. Split the Linux debug information from the executable and keep the companion from this exact build:

objcopy --only-keep-debug build/native-crash build/native-crash.debug
objcopy --strip-debug build/native-crash
(cd build && objcopy --add-gnu-debuglink=native-crash.debug native-crash)

curl --fail --location --silent --show-error \
    https://github.com/getsentry/sentry-cli/releases/download/3.8.2/sentry-cli-Linux-x86_64 \
    --output .vendor/sentry-cli
chmod +x .vendor/sentry-cli
.vendor/sentry-cli debug-files check build/native-crash.debug

Set SENTRY_AUTH_TOKEN to the project-scoped token, then upload the companion before distributing or running that build. Bugsink has no organization object, so --org is a compatibility placeholder; --project must be the real Bugsink project slug:

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 \
    build/native-crash.debug

--include-sources creates the source bundle used for the code around each frame. Keep the exact debug companion for every released build: recompiling the same source can produce a different debug ID.

Send a test crash

Temporarily call a path that really terminates the process. This fixture raises SIGSEGV inside reserve_product() and prevents the compiler from folding the small function out of the demonstration stack:

#if defined(__GNUC__) && !defined(__clang__)
__attribute__((noinline, noipa))
#elif defined(__clang__)
__attribute__((noinline))
#endif
static void
reserve_product(const char *sku)
{
    if (strcmp(sku, "coffee") == 0) {
        printf("Reserved one %s\n", sku);
        return;
    }

    fprintf(stderr, "Product %s is not in inventory\n", sku);
    fflush(stderr);
    if (raise(SIGSEGV) != 0) {
        abort();
    }
}

Run the application with the DSN shown by your Bugsink project:

export SENTRY_DSN=https://key@bugsink.example/1
export SENTRY_DATABASE_PATH=/var/lib/your-application/crashpad

build/native-crash missing-product

The process exits because of the signal; that is the expected test result. Crashpad continues in its separate handler process and uploads the minidump.

See the crash in Bugsink

Open the new issue in Bugsink. Its crashing stack contains the application function, source filename, line number, and source around the deliberate signal.

Bugsink preview

That’s it: native crashes from this build now arrive with a readable application stack. Remove the deliberate crash and keep the SDK initialization, handler, persistent database, and debug-file upload in your normal build and deployment.

What Bugsink receives

Crashpad sends a compact binary minidump after the application terminates. It contains the crashing thread, other thread stacks, loaded modules, operating system, CPU architecture, and a debug ID for each module. The matching debug companion turns the addresses for your application module into source-level frames.

Each first-party executable or shared library has its own debug ID. Upload the matching debug information for every module whose frames you want to read. The minidump documentation also covers direct Crashpad and Breakpad upload URLs, other debug-file formats, and troubleshooting.

Current limitations

This complete path is verified on Linux x86-64 with sentry-native 0.17.6 and its Crashpad backend. macOS, other architectures, Breakpad, and framework SDKs still need their own end-to-end test applications before they get the same claim.

The direct Crashpad request includes non-empty __sentry-event and __sentry-breadcrumb1 multipart file parts. Bugsink’s direct-minidump parser currently reads only regular request.POST fields; those sentry-native parts land in request.FILES and are not merged into the event. The stored event therefore does not retain the release, SDK identity, tags, extra data, or breadcrumb which the sample set before crashing. Crash receipt, threads, modules, symbolication, and source context do work.

As of November 19, 2026, the open Bugsink issue #597 reports that Windows minidumps are accepted but dropped during background processing. PDB debug IDs include an age suffix which Bugsink passes to a UUID parser that rejects it. Do not read the successful Linux result as a Windows support claim.

Debug files must arrive before the crash. Bugsink symbolicates during ingestion, so uploading a missing file later does not repair an existing event. Bugsink also does not extract local variables from minidump memory, and removes the original dump after processing rather than retaining it for download.

When testing a source checkout, run Bugsink behind a production webserver such as Gunicorn. Crashpad uses chunked transfer encoding, which Django’s development server does not handle.