Crash handler

src/crash_handler.zig (~96 KB — the third-largest Zig file in the repo) is the panic/segfault entry point for the entire process. It produces stack traces, opt-in crash reports, and demangled tracebacks that link back to source positions.

What it does

• Installs platform signal handlers for SIGSEGV, SIGBUS, SIGFPE, SIGILL, SIGABRT (POSIX) and a vectored exception handler (Windows).
• On crash:
  1. Captures CPU registers and a backtrace via libunwind (Linux/macOS) or RtlCaptureStackBackTrace (Windows).
  2. Resolves Zig and JS frames (Bun__remapStackFramePositions walks the source-map table held by VirtualMachine.zig).
  3. Demangles symbols.
  4. Encodes the trace as a bun.report URL (a https://bun.report/... link with a base64 payload).
  5. Prints a friendly message asking the user to share the URL.
  6. Optionally uploads to bun.report (gated by bun upgrade --canary style env vars).
• Provides bun.handleOom(...) and bun.outOfMemory() so OOM converts to a crash with a stable trace rather than unreachable.

Why a custom handler

Stock signal handlers print "Segmentation fault" and exit. That's nearly useless for a multi-language runtime. Bun's handler:

• Names the function inside Zig where the crash originated.
• Includes the JS stack at the same time, so a panic deep in Zig that was triggered by user JS shows both halves.
• Persists the stack to a file with BUN_DEBUG_CRASH_FILE=/path so CI logs survive process termination.

Crash report URLs

bun.report is a service at https://bun.report/ operated by Oven. The crash handler builds a URL like https://bun.report/<arch>-<os>-<version>/<encoded trace>. The receiving service decodes the trace, demangles further with the matching debug symbols, and shows a human-friendly page. The encoder is shared with bun-tracestrings (a small companion package, see package.json's devDependencies).

Users have to opt in to actual upload; by default, only the URL is printed.

Test infrastructure

The crash handler has unit tests under test/internal/ that deliberately crash and assert the resulting trace. These run only on platforms where backtraces are reliable.

Integration with allocator

bun.handleOom(expr) from src/handle_oom.zig wraps allocator calls so error.OutOfMemory becomes a crash with a meaningful trace, while non-OOM errors are propagated. This is the project's standard idiom — the comment in src/CLAUDE.md warns against expr catch bun.outOfMemory() because it swallows non-OOM errors silently.

Integration points

• Allocator — src/handle_oom.zig, src/allocators/. OOM and panic share the same path.
• Source maps — src/sourcemap/, src/bun.js/SavedSourceMap.zig. Used to translate native PCs to file:line.
• VM — VirtualMachine.zig exposes the active source-map table during a crash.
• Bun__panic — Exported symbol called by Zig and C++ panics.

Entry points for modification

• To change the payload format, edit the encoder near the bottom of crash_handler.zig. Match it on the bun.report server side.
• To add a new signal, register it alongside the existing ones in the platform-specific install path.
• To change OOM behaviour, edit src/handle_oom.zig.

Key source files

File	Purpose
src/crash_handler.zig	Signal handler + report encoder.
src/handle_oom.zig	OOM → crash bridge.
src/sourcemap/	Source map decoder.
src/bun.js/SavedSourceMap.zig	Per-VM source map table.