solvecraft/docs/crash-reports.md

Crash reports

When the desktop app crashes or hits an internal error, it writes a crash report on this computer. Each report holds enough to reproduce and fix the problem: in most cases the design and the exact commands that trigger it. Reports are never sent anywhere. To share one, use Report… in Help ▸ Crash Reports…, which opens a GitHub issue draft. Nothing is shared until you review and submit it, and the design is not part of the draft.

To send a report:

1. Review the title, report text and screenshot in SolidCraft, then click Open GitHub issue form (Open GitHub in narrow windows). SolidCraft copies the report text to your clipboard and opens GitHub. Short reports are also filled in through the URL; paste longer reports into the GitHub draft.
2. Attach the screenshot if you want to share it: use Copy screenshot and paste it into GitHub, or use Save screenshot… and upload the PNG. Screenshots are not attached automatically.
3. Click Submit new issue on GitHub to publish the report. Opening the draft alone does not send it.

Submission and fallback behavior

The same reviewed report dialog is used by Report a bug, command errors and crash reports. Desktop and web builds submit through GitHub in the browser; the dialog has no direct submission API and needs no GitHub token in SolidCraft. It explains this beside the public-report/account notice. Sign in with a GitHub account to publish the report.

Copy report and Open GitHub issue form remain available without credentials or a connection. Copying works even before the required description is filled in; opening GitHub with an empty description instead focuses that field and explains what is missing. Neither action closes the draft. On narrow windows the footer uses Open GitHub and Copy report; close the draft with the header's close button. The two export actions must remain visible at high UI zoom.

If offline, a browser launch is blocked, or GitHub cannot be reached, the dialog tells the user to copy the report and keep the text to submit later. Opening GitHub requests a clipboard copy even for short reports. SolidCraft cannot confirm browser launch, clipboard delivery or submission; the draft stays editable for retrying. Copying or opening a report does not modify the design or its undo history.

Where they are

<data dir>/solidcraft/crashes/, next to the recovery folder:

System	Folder
Linux	~/.local/share/solidcraft/crashes (or $XDG_DATA_HOME/solidcraft/crashes)
Windows	%LOCALAPPDATA%\SolidCraft\crashes
macOS	~/Library/Application Support/SolidCraft/crashes

SOLIDCRAFT_CRASH_DIR overrides the folder. solidcraft --crash-log and solidcraft-cli crashes dir print it.

For agents

All of these read the same folder:

From	List	One report	Delete
Engine command (MCP execute, control channel, scripts)	diagnostics.crash_reports {limit?}	diagnostics.crash_report {id}	diagnostics.crash_reports.clear {id?}
MCP tool	crash_reports {limit?}	crash_reports {id}	—
CLI	solidcraft-cli crashes [--json]	solidcraft-cli crashes show <id>	solidcraft-cli crashes clear [<id>]
Control channel (UI)	ui.help {"item": "crashes"} opens the window

Reproduce: solidcraft-cli crashes replay <id> opens the report's design, runs its commands, and reports whether the same internal error happens again (same place and message). Without the CLI, run solidcraft-cli run <report>/replay.json --in <report>/design.sc. A fixed crash turns into a regression test with the same two files.

Check that reporting works: with SOLIDCRAFT_CRASH_TEST=1 set for the app, the command diagnostics.crash_test has three modes:

• panic: an internal error in a command
• kernel: an internal error inside the geometry kernel
• abort: the app ends at once, and the report appears at the next start. On macOS the signal handler catches it, so the report names SIGABRT and the frames that called abort().

What a report holds

A folder crashes/<YYYYMMDD-HHMMSS>-<signature>/:

• report.json ("format": "solidcraft-crash/1"):
  • kind: one of
    • command_panic: a command hit an internal error; it was caught and the design was left unchanged
    • kernel_panic_recovered: the third-party geometry kernel panicked and was caught. This is harmless on the desktop, but it would crash the web build.
    • panic: an internal error outside any command
    • unclean_exit: a previous session ended without recording a clean exit. It is detected at the next start, which may be days later. Possible causes include an abort, a stack overflow, a segfault, a crash inside a graphics driver, a system shutdown, or the process being forcibly stopped. This kind alone does not identify the cause. When the app died while starting up, the message and location name the startup step (see below). On Windows and macOS, a captured native crash also says the exception or signal, the module it happened in and the offset into it.
  • message, location (file:line), thread
  • backtrace: frames symbol (file:line), without the panic machinery, std internals or the user's home folder
  • app (version, commit, build date), system (OS, architecture, renderer and GPU), session.uptime_s
  • command: the command that crashed, with its parameters
  • recent_commands: up to 32, with ok or error
  • base: what the replay starts from (the design before the command, an autosave, a saved file or a new design)
  • count: how many matching reports have been recorded; repeats update the existing report.
  • first_seen, last_seen: UTC timestamps when the report was first and most recently recorded. For unclean_exit, these are detection times at a later launch, not the exact times the sessions ended. The session start in message may be much earlier; the report does not imply a failure in the currently open design.
  • notes: what is missing and why, for example a design too large to copy
  • startup_phase: {step, ms} when the app died before it drew its first frame: the step it was in (window, graphics instance, window surface, adapter request, adapter chosen, device creation, egui renderer (shader compile), surface configure, app setup, viewport pipelines (shader compile), first frame, first frame (present)) and how many milliseconds after launch it began. system.environment names the renderer (backend, GPU, driver) as soon as the adapter is picked, so it is there even when the device never started.
  • native (Windows and macOS): what the native crash handler caught: code, name, address (of the faulting instruction), module, offset (into the module), detail (for an access violation or a segfault, the address read or written) and thread. The backtrace then shows the same in two lines.
    • On macOS, where a signal handler catches SIGSEGV, SIGBUS, SIGILL, SIGFPE, SIGTRAP and SIGABRT, code and signal are the signal's name (SIGSEGV), name says it in words (segmentation fault, or stack overflow when the fault is just below the thread's stack), and it adds si_code, thread_name, pid and frames: up to 24 module+offset symbol+offset lines walked up the frame pointers from the faulting instruction, which the backtrace lists too. The process still ends with the signal, so macOS also writes its own crash report, with every thread's stack: ~/Library/Logs/DiagnosticReports/solidcraft-<date>.ips (Console ▸ Crash Reports), whose pid is the one in native.
• design.sc: the design the replay starts from
• replay.json: {"commands": [{command, params}, …]}
• minidump.dmp (Windows, native crashes; on macOS, see the system's own report above): the threads' stacks and the loaded modules at the crash, for WinDbg or Visual Studio. It holds stack memory only, not the design, but it stays on this computer like the rest of the report; share it only on request.

A crash that ends the process without any exception (a fail-fast, which is how an abort ends on Windows) still gets the startup step. Windows can also keep its own dumps of every crash: set DumpFolder under HKLM\SOFTWARE\Microsoft\Windows\Windows Error Reporting\LocalDumps.

How it stays cheap and small

• Before a crash: the app keeps a journal of the top-level commands run on the design on screen (crashes/sessions/*.jsonl, at most 512 KB). Each command adds two small writes, with no flush to disk. Previews and other scratch sessions are not recorded. Each autosave restarts the journal from the autosaved design. A clean exit deletes it. The journal file is locked while its app runs, so at the next start, a journal nobody holds belongs to an app that died.

• A panic captures its backtrace only the first time its signature is seen. The signature is the place plus the message, with numbers ignored.

• Limits:

  • at most 5 new reports per run
  • 20 reports
  • 50 MB in total
  • 90 days
  • a design over 10 MB is not copied; the report notes that

  When over a limit, recovered kernel panics are deleted before real crashes, and the oldest first.

• Where it's off: the CLI, tests and the web build never install the hook. There, commands pay only a check of one atomic flag.

Release builds keep line tables (debug = "line-tables-only"), so backtraces name the file and line. Stripping a binary (strip) removes them, and the function names too.