Crate bun_crash_handler 

This file contains Bun’s crash handler. In debug builds, we are able to print backtraces that are mapped to source code. In release builds, we do not have debug symbols in the binary. Bun’s solution to this is called a “trace string”, a url with compressed encoding of the captured backtrace. Version 1 trace strings contain the following information:

• What version and commit of Bun captured the backtrace.
• The platform the backtrace was captured on.
• The list of addresses with ASLR removed, ready to be remapped.
• If panicking, the message that was panicked with.

These can be demangled using Bun’s remapping API, which has cached versions of all debug symbols for all versions of Bun. Hosting this keeps users from having to download symbols, which can be very large.

The remapper is open source: https://github.com/oven-sh/bun.report

A lot of this handler is based on the Zig Standard Library implementation for std.debug.panicImpl and their code for gathering backtraces.

Modules

cli_state

cpu_features

debug

handle_oom

Structs

ActionGuard

RAII guard returned by scoped_action / set_current_action_resolver. Restores the previous CURRENT_ACTION on drop (Zig: defer current_action = old).

FmtAdapter

Wrap a core::fmt::Write sink (typically &mut core::fmt::Formatter) so it can be passed where a byte-level Write is expected.

StackTrace

Zig: std.builtin.StackTrace — slice of return addresses + cursor.

StoredTrace

Zig: src/crash_handler/crash_handler.zig::StoredTrace — fixed 31-frame buffer.

WriteStackTraceLimits

Zig: WriteStackTraceLimits.

Enums

Action

CrashReason

This structure and formatter must be kept in sync with bun.report’s decoder implementation.

TraceSeed

Where the crash trace is seeded from. Each call site has exactly one.

Constants

CURRENT_ACTION

This can be set by various parts of the codebase to indicate a broader action being taken. It is printed when a crash happens, which can help narrow down what the bug is. Example: “Crashed while parsing /path/to/file.js”

Traits

Write

Byte-level write sink — port of Zig std.Io.Writer.

Functions

append_pre_crash_handler

For large codebases such as bun.bake.DevServer, it may be helpful to dump a large amount of state to a file to aid debugging a crash.

crash_handler

This function is invoked when a crash happens. A crash is classified in CrashReason.

current_action

Snapshot the thread-local CURRENT_ACTION for save/restore around a scoped operation (e.g. js_printer::print_with_writer_and_platform).

dump_current_stack_trace

dump_stack_trace

Version of the standard library dumpStackTrace that has some fallbacks for cases where such logic fails to run.

fix_dead_code_elimination

handle_root_error

This is called when main returns a Zig error. We don’t want to treat it as a crash under certain error codes.

init

is_panicking

panic_impl

print_metadata

remove_pre_crash_handler

reset_on_posix

scoped_action

Scoped CURRENT_ACTION = action. Snapshots the previous value, installs action, and returns an ActionGuard that restores the previous value on drop. Zig: const old = current_action; defer current_action = old; current_action = ...;.

set_current_action_resolver

Scoped CURRENT_ACTION = .resolver{...}. Zig (resolver.zig:672-679) sets this only under Environment.show_crash_trace because module resolution is extremely hot and has a low crash rate; the cfg-gate here mirrors that.

sleep_forever_if_another_thread_is_crashing

Zig: crash_handler.sleepForeverIfAnotherThreadIsCrashing.

suppress_core_dumps_if_necessary

If POSIX, and the existing soft limit for core dumps (ulimit -Sc) is nonzero, change it to zero. Used in places where we intentionally crash for testing purposes so that we don’t clutter CI with core dumps.

suppress_reporting

From now on, prevent crashes from being reported to bun.report or the URL overridden in BUN_CRASH_REPORT_URL. Should only be used for tests that are going to intentionally crash, so that they do not fail CI due to having a crash reported. And those cases should guard behind a feature flag and call right before the crash, in order to make sure that crashes other than the expected one are not suppressed.

write_stack_trace

Clone of debug.writeStackTrace, but can be configured to stop at either a frame count, or when hitting jsc LLInt Additionally, the printing function does not print the ^, instead it highlights the word at the column. This Makes each frame take up two lines instead of three.

write_u64_as_two_vlqs