compile: exit with an error instead of SIGBUS when a standalone executable is truncated

[robobun]

Problem

• A bun build --compile executable whose file on disk is shorter than it should be (download or copy cut short) still starts, then dies before any user code runs with panic(main thread): Bus error at address 0x... in StandaloneModuleGraph::from_executable, followed by the "Bun has crashed" banner and a bun.report link.
• This is the biggest family of startup crash reports from Linux compiled executables (Sentry BUN-36MW, BUN-3PTA, BUN-39RY, BUN-3Q6K, BUN-4B1N). Within one build the fault address is a constant repeated across many machines: the address of the payload trailer.
• Cause: write_bun_section (src/exe_format/elf.rs) grows the RW PT_LOAD so the kernel maps the payload at exec. Linux maps the segment's full p_filesz without checking that the file is that long, so a short file execs fine, and the first read of a page the file does not back raises SIGBUS. That read is the trailer compare in from_executable (src/standalone_graph/StandaloneModuleGraph.rs, Linux branch), or the length header in elf::get_data if the cut landed right at the start of the payload.

Fix

• from_executable now goes through elf::get_data_or_exit_if_truncated(), which calls madvise(MADV_POPULATE_READ) on the page holding the length header before reading it, and on the page holding the last byte of the payload (the trailer) before from_executable reads that. EFAULT prints an error and exits 1; every other result (EINVAL on kernels older than 5.14, ENOMEM, ...) falls through to the same unchecked read as before. hint_source_pages_dont_need keeps using the plain get_data().
• The message names the file (self_exe_path, called on the error path only):

  error: "/tmp/x/app" is incomplete: the file ends before the program embedded in it does.
  note: It was probably truncated while being downloaded or copied. Re-download or reinstall it and try again.
  

• Why this is correct:
  • MADV_POPULATE_READ faults the page in exactly the way the read that follows would, and reports the condition that would have been a SIGBUS as EFAULT. Since the page is then already mapped, the read after it takes no fault: on a complete binary the two probes replace two page faults, and a plain bun returns before probing (BUN_COMPILED.size == 0).
  • Truncation removes a suffix of the file. The trailer is the last thing in the payload, so its page being on disk implies every page from_bytes and the runtime read later is too; the header probe covers the one page before that. Together they cover every cut point inside the payload. A cut before the payload lands in bun's own .data/.bss and fails in ld.so or libc before main, where there is no crash handler to misattribute it.
  • Intentionally unchanged: a cut inside the payload's final page. That page is still readable (zero-filled past EOF), so there is no SIGBUS to prevent; the trailer check that already exists sees garbage and takes its existing fallback of running as a plain bun (checked: such a binary answers --version, before and after this PR). What an invalid trailer should do is the corruption question Don't crash at startup when a standalone executable's embedded graph is corrupted #31787 is about, not truncation.
  • Only EFAULT is fatal, and it is the one error madvise documents for this exact condition. Anything that does not implement the advice (kernels before 5.14, emulation layers) returns EINVAL, the documented error for unknown advice, and keeps today's behaviour. bun's allocator and JSC already call madvise at startup, so no sandbox sees a new syscall.
  • The executable is never opened or stat'd. compile: fail gracefully instead of SIGBUS on truncated standalone binary #29665 fixed the same bug with stat("/proc/self/exe") plus a program header walk and was declined for exactly that ("we should not need to stat or read the executable"). Not touching the file is also what keeps execute-only (chmod 111) binaries working, which the mmap-at-exec design exists for; page faults do not check file permissions. It is also why the message carries no byte counts.
  • Only the ELF path changes. XNU, Windows and FreeBSD refuse an image whose segments extend past the end of the file at exec time (and the crash family above is Linux-only), so there is nothing to probe there; the FreeBSD build of get_data_or_exit_if_truncated is get_data().
  • A corrupted length field (Don't crash at startup when a standalone executable's embedded graph is corrupted #31787) behaves as today: probing the resulting address returns ENOMEM, which is ignored.
• Verified with test/bundler/bun-build-compile.test.ts > "truncated compiled binary exits with an error instead of SIGBUS": compiles an app with a 1 MiB payload, finds the payload through the .bun section header (under debug+ASAN hundreds of MB of debug info follow it, so cutting from the end of the file would miss), runs the intact binary, then runs copies cut 64 KiB into the payload (trailer probe) and at the payload start (header probe), asserting the exact stderr, empty stdout and exit code 1.
  • Unfixed build: the test fails with the Bus error (release: crash banner, exit 135; ASAN build: ASAN BUS report). Copies rather than truncating in place: the file that was just executed stays ETXTBSY for a few tens of ms after the child is reaped. The cut binaries run with detect_leaks=0 because LSAN's exit scan of the process would itself SIGBUS on the unbacked pages, which is what CI's ASAN_OPTIONS would otherwise hit; verified with CI's options locally.
  • bun-build-compile.test.ts, compile-argv.test.ts, compile-asset-bunfs.test.ts and bundler_compile.test.ts pass on the debug build (the latter except compile/HelloWorldWithProcessVersionsBun, which fails on main with any debug build and is fixed by test(bundler): fix compile/HelloWorldWithProcessVersionsBun on debug builds #37373). Every compiled binary those tests run goes through the two probes, so they also cover the no-false-positive side, including the execute-only cases.
  • cargo clippy -p bun_standalone_graph is clean for linux-gnu, linux-musl, android and freebsd targets.
• Supersedes compile: detect truncated standalone executables before they SIGBUS #35134, which used the /proc/self/exe approach from compile: fail gracefully instead of SIGBUS on truncated standalone binary #29665 (run from main()). Complementary to Don't crash at startup when a standalone executable's embedded graph is corrupted #31787, which validates the stored length and vaddr of a full-length file and does not detect truncation.

Background

• Standalone layout on Linux: bun build --compile appends [u64 payload_len][payload] at a page-aligned offset inside the template's RW PT_LOAD, extends that segment's p_filesz/p_memsz over it, and writes the payload's virtual address into BUN_COMPILED, the 8-byte variable in the original .bun section (0 in a plain bun). At startup elf::get_data dereferences that address; nothing is read from the file system. The payload ends with the Offsets struct and the 16-byte TRAILER, which from_executable checks before anything else.
• SIGBUS on a file mapping: file-backed pages are faulted in lazily. Touching a page whose file offset lies entirely past the end of the file raises SIGBUS (the page containing EOF itself reads as zeros past EOF). Exec itself succeeds for a truncated executable because the headers and the code at the front of the file are intact, so this fault is the only symptom.
• MADV_POPULATE_READ (Linux 5.14, 2021): prefault a range for reading. Returns EFAULT when a page in the range would raise SIGBUS on access, EINVAL on kernels that do not know the advice, ENOMEM when the range is not mapped.

Repro and before/after output

head -c 1048576 /dev/zero | tr '\0' x > big.txt
cat > main.ts <<'EOF'
import big from "./big.txt" with { type: "text" };
console.log("hello", big.length);
EOF
bun build --compile main.ts --outfile app
readelf -SW app | grep ' .bun '        # sh_offset of the relocated payload, e.g. 4709000
cp app cut && truncate -s $((0x4709000 + 65536)) cut && ./cut; echo "exit=$?"

Before (bun 1.4.0 canary):

panic(main thread): Bus error at address 0x4AD50D7
oh no: Bun has crashed. This indicates a bug in Bun, not your code.
...
exit=135

0x4AD50D7 = payload vaddr 0x49D5000 + 8 + payload_len - 16, i.e. the trailer compare. Truncating to exactly the payload start faults at 0x49D5000, the length header.

After:

error: "/tmp/x/cut" is incomplete: the file ends before the program embedded in it does.
note: It was probably truncated while being downloaded or copied. Re-download or reinstall it and try again.
exit=1

[coderabbitai]

Warning

Review limit reached

@robobun, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 44 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 90a96ccc-38ab-4d53-b0ef-b0f9dfaed9f3

📥 Commits

Reviewing files that changed from the base of the PR and between 1805964 and b08eb4b.

📒 Files selected for processing (2)

• src/standalone_graph/StandaloneModuleGraph.rs
• test/bundler/bun-build-compile.test.ts

---

_{Comment @coderabbitai help to get the list of available commands.}

[robobun]

Status: ready for review.

Reproduced on bun 1.4.0 canary (Linux x64): bun build --compile an app with a 1 MiB embedded file, truncate the output anywhere inside the payload, run it. It dies with panic(main thread): Bus error at address 0x4AD50D7 (the trailer compare in from_executable) and exit 135; truncated exactly at the payload start it faults on the length header instead. Both cut points are covered by the new test in test/bundler/bun-build-compile.test.ts, which fails on the unfixed build and passes with this branch, including under CI's ASAN options.

Supersedes #35134 (the /proc/self/exe stat approach that was declined in #29665); #31787 covers the separate corrupted-length case.

[claude]

I reviewed this PR and didn't find any bugs. Because it changes the startup path of every compiled Linux binary and picks a specific approach (MADV_POPULATE_READ probing) over alternatives that were previously declined (#29665, #35134), a maintainer sign-off on the mechanism would still be worthwhile.

What was reviewed:

• get_data() refactor into get_blob() + get_payload() is behavior-preserving; len >= 8 is guaranteed before len - 1, and wrapping_add handles a corrupted length by landing on an unmapped page (ENOMEM, ignored).
• Only EFAULT triggers exit; EINVAL on pre-5.14 kernels and every other errno fall through to the existing unchecked read, so old kernels keep today's behavior.
• Plain bun returns before probing (vaddr == 0); FreeBSD build compiles to plain get_data(); execute-only binaries stay working since nothing opens the file.
• Test correctly locates the payload via section headers (avoids loading the ~1 GB debug binary), gates on kernel 5.14+, disables LSAN for the truncated runs, and copies before truncating to dodge ETXTBSY.

Extended reasoning...

Overview

This PR converts a SIGBUS crash into a clean error message when a bun build --compile executable on Linux has been truncated (e.g., interrupted download). It refactors elf::get_data() in src/standalone_graph/StandaloneModuleGraph.rs into get_blob() + get_payload(), adds get_data_or_exit_if_truncated() (Linux/Android: probes the length-header page and the trailer page with madvise(MADV_POPULATE_READ) and exits with an error:/note: message on EFAULT; FreeBSD: identical to get_data()), and switches from_executable to call it. A new Linux-only test in test/bundler/bun-build-compile.test.ts compiles a binary, locates the .bun section via ELF headers, and asserts the exact error output for two truncation points plus success on the intact binary.

Security risks

None identified. The change reads no user-controlled input beyond what from_executable already reads (the mapped payload). madvise is called on an address derived from the process's own segment mapping; the only new filesystem access is self_exe_path() (readlink of /proc/self/exe) on the error path only. The wrapping_add on the untrusted len means a garbage length lands on an unmapped page and madvise returns ENOMEM, which is ignored — same behavior as today.

Level of scrutiny

High. This code runs unconditionally at startup of every compiled standalone binary on Linux/Android, before any user code. A false positive would break every compiled app. The mitigations look sound — plain bun returns before the first probe, only EFAULT triggers exit, and the existing compile test suite (execute-only, large-payload, patchelf, WSL1-shape) all run through the two probes and would catch a false positive — but a maintainer should confirm the MADV_POPULATE_READ approach is the one they want, given that two prior PRs (#29665, #35134) took different approaches and one was explicitly declined.

Other factors

The PR description is unusually thorough and pre-emptively addresses the review criteria: it explains why stat/open were avoided (prior maintainer feedback + execute-only binaries), why only two pages need probing (trailer is last, header is first), why FreeBSD/macOS/Windows are excluded (their loaders reject short images at exec), and documents USE_SYSTEM_BUN=1 failure, ASAN behavior, and clippy across all four cfg targets. The test follows harness conventions (tempDir, bunEnv spread, concurrent pipe drain, combined-object assertion, skipIf with a stated reason, per-test timeout with the same justification as the neighboring #29963 test). The refactor of get_data() preserves the write-provenance comment and the payload_len < 8 guard. I found nothing to flag; deferring only because the mechanism choice is a design decision with history in this repo.

[robobun]

^{Updated 7:00 PM PT - Aug 13th, 2026}

✅ @robobun, your commit b08eb4b8a0fb7faee2a08d10af91f844caaf4d1b passed in Build #95014! 🎉

---

🧪   To try this PR locally:

bunx bun-pr 38251

That installs a local version of the PR into your bun-38251 executable, so you can run:

bun-38251 --bun

[robobun]

Reached the same root cause from the newer Sentry groups (BUN-4E9B and BUN-4D8P: the same crash under the Rust symbol names, 132 events, plus the older BUN-3PTA, BUN-3Q6K and BUN-3RHW groups). Notes for whoever picks this up:

• The branch is now dirty against main: StandaloneModuleGraph.rs and bun-build-compile.test.ts both changed since 08-14. It needs a rebase before review.
• The red lane on build 95014 is unrelated flakes (child_process_ipc_handle.test.ts, napi.test.ts).
• MADV_POPULATE_READ needs Linux 5.14. On 5.10 (Debian 11, Amazon Linux 2) and 5.4 (Ubuntu 20.04) the probe returns EINVAL and the SIGBUS stays. A fallback that touches no file on any kernel: record the payload range, and let the crash handler print the truncation message for a SIGBUS whose fault address lies inside that range, instead of the crash banner and the report upload.
• Reference branch with the file-size variant (an O_PATH open of /proc/self/exe plus fstat, so it needs no read permission and qemu-user redirects it to the emulated binary) and a test that cuts inside the payload: https://github.com/oven-sh/bun/tree/farm/efc9a72d/compile-truncated-elf. Not opened as a PR, since compile: fail gracefully instead of SIGBUS on truncated standalone binary #29665 was declined for reading the executable's metadata.