Skip to content

Save a crash report when fx gets a segfault - #2165

Draft
fazxes wants to merge 9 commits into
mainfrom
fazxes/save-segfault-crash-report
Draft

fazxes wants to merge 9 commits into
mainfrom
fazxes/save-segfault-crash-report

Conversation

@fazxes

@fazxes fazxes commented Nov 21, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

  • A segfault, bus error, illegal instruction, or arithmetic fault in fx now prints the signal and its address before fx exits, plus a stack trace in builds with debug info. Before, fx ended with no message, because fx's own C main never attached Zig's segfault handler.
  • In an interactive session, fx also saves a crash report for it to ~/.fx/diagnostics/last-crash.jsonl, with error signal and a message such as Segmentation fault at address 0x1234 (pc 0x..., handleSegfault+0x...), and prints fx: crash report saved to <path> or fx: crash report not saved. The program counter and its offset let an unstripped build of the same commit map the fault to a line, since the abort hides it from the system crash report. The next /trace includes it, under the same 24-hour rule as other crash reports. Zig's default handler only prints, and that text is gone once the terminal closes, so the saved report is what a user can still send after reopening fx.
  • After such a signal, fx exits with SIGABRT, as it does after a panic, instead of the original signal.
  • A crash signal after fx already saved the full crash report does not replace it, as with a panic.

Check findings

  • fuzz-reached: the four targets in changed files (agents_menu_selection, trace_record_text, trace_review_records, subagent_task_line) each ran 60 seconds with status ok.
  • concurrency-added: the signal stack and segfault handler setup in main. A Thread Sanitizer run on this branch (run 44972802102, at 364d286) has the same 5 warnings as main's latest nightly run, and none names src/main.zig or crash_panic.zig. The later merges from Save a crash report when fx stops on an error or a panic #2139 add no threads or locks.

Docs: vercel-labs/fx-web#350

Stacked on #2139.

fx exports its own C main, so Zig's start code never attached its
segfault handler, and a segfault ended fx with no message and no
crash report. main now sets up the signal stack and attaches the
handler, as Zig's start code does.

The handler calls root.debug.handleSegfault, which saves a crash
report like a panic does, with error "signal" and a message such as
"Segmentation fault at address 0x1234". It then calls Zig's default
handler, which prints the signal and a stack trace and aborts. This
covers SIGSEGV, SIGBUS, SIGILL, and SIGFPE.
@fazxes fazxes added the type: improvement Improves existing user-facing behavior label Nov 21, 2026
Brings in the crash handler's new save, which removes the temp path and
creates it as a new 0600 file, and the creation of ~/.fx. The tests
from #2139 now pass the error name that this branch adds to saveRecord.
Release builds are stripped, so Zig's segfault handler prints the
signal and its address and says that stack tracing is disabled. The
comments now say a stack trace prints only in builds with debug info.
The two signal record tests share one setup helper.
handleSegfault now calls claimSave, the shared name for the same check
on the same flag, so a segfault after a saved full report also keeps it.
A crash signal ends in abort, so the system crash report no longer
points at the fault, and a release build prints no stack trace. The
saved message now holds the program counter and its offset from
handleSegfault, which an unstripped build of the same commit can map
to a line.

A comment notes that a signal sent with kill has no fault address, so
the saved address is then the sender's ids. The e2e test also checks
the SIGABRT exit, and the module's comments cover segfaults.
Panics and crash signals now go through one saveOnce gate, which
claims the save and writes through #2139's folder-descriptor save, so
a crash signal also prints the saved or not-saved line and keeps a
saved full report.
@fazxes
fazxes changed the base branch from fazxes/save-crash-report to main November 22, 2026 21:00

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

type: improvement Improves existing user-facing behavior

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant