How do you diagnose Electron main process hangs in VS Code-like apps?

[Kong (Kitaharakasusa)]

Hi VS Code community,

I am not reporting a VS Code bug here. I am working on an Electron-based desktop application, and I would like to learn from the practices used by projects like VS Code when diagnosing main process hangs/freezes.

In our case, the hard part is that when the Electron main process is stuck, the usual debugging channels can become unavailable or too late to attach. The renderer may still show the last frame, but IPC, menus, window management, and app-level actions stop responding. These cases are often intermittent and difficult to reproduce locally.

For people who have worked on VS Code, Electron apps, or similar desktop applications:

• What signals do you usually collect when the main process becomes unresponsive?
• Do you rely on process dumps, V8 CPU profiles, Node diagnostic reports, Electron crash reports, custom watchdogs/heartbeats, or something else?
• How do you capture useful data when the process is hung but has not crashed?
• Are there VS Code patterns, docs, source files, or diagnostic commands that are especially worth studying?
• How do you distinguish between common causes such as synchronous filesystem work, IPC overload, native module issues, event-loop starvation, extension-related pressure, or OS-specific blocking calls?

I am especially interested in practical workflows: what to instrument in advance, what users can provide after a hang, and how maintainers turn those artifacts into a likely root cause.

I realize this Discussions repo is primarily for extension development Q&A. If this question is off-topic here, I would appreciate a pointer to the right VS Code/Electron community channel.

Thanks!

[Joel (aspire488)]

For intermittent main-process hangs, I would treat this as an observability problem first rather than relying on attaching a debugger after the fact.

A workflow I've found useful is to instrument the application so that a hang produces artifacts even when the normal IPC/UI path is no longer responsive.

1. Add a lightweight main-process watchdog

Keep a timer/heartbeat in the main process and record event-loop delay rather than only checking whether the process is alive. A process can have a valid PID and still be effectively dead because the main JS thread is blocked.

Record at least:

• timestamp
• event-loop delay/max delay
• CPU usage
• RSS/heap usage
• active window/process IDs
• recent IPC/request activity
• extension/plugin activity if applicable

2. Capture a Node diagnostic report

Node's diagnostic report is particularly useful for this type of failure because it can contain both JavaScript and native stack information, V8/heap information, libuv handles, resource usage, and platform information.

For example, Node supports:

--report-on-signal

with SIGUSR2 as the default report signal on supported POSIX platforms.

That gives you a useful "snapshot while the process is still alive" rather than waiting for a crash.

One caveat is important: Node documents signal-triggered reports as unsupported on Windows, so I would provide an OS-specific collection mechanism rather than assuming SIGUSR2 works everywhere.

3. Keep an external watchdog

For a genuinely hung main process, I would not make the watchdog part of the same event loop that it is trying to diagnose.

Have a small external process/service periodically check a heartbeat emitted by the Electron main process. If the heartbeat stops progressing, the watchdog can record the PID and collect an OS-level process dump/minidump or other platform-specific diagnostic artifact.

That is much more useful than an in-process timeout when the main thread itself is blocked.

4. Use the V8 inspector when the problem is reproducible

Electron supports --inspect / --inspect-brk for debugging the main process. With the inspector available, CPU profiling can help distinguish a JavaScript hot loop from time spent waiting elsewhere.

For an intermittent production hang, however, I would treat inspector profiling as a reproduction tool rather than the primary incident-capture mechanism.

5. Separate CPU starvation from synchronous/native blocking

This distinction is important when interpreting the artifacts:

• High main-thread CPU + repeated JS frames → likely JS/event-loop starvation or a hot loop.
• Low CPU + main-thread stack inside synchronous fs/crypto/child-process/native code → potentially blocking I/O or native work.
• Large IPC backlog + otherwise healthy process → investigate message volume, serialization, and handlers.
• Main thread appears idle but a native call never returns → investigate native modules/OS APIs.
• Only certain extensions reproduce it → compare extension-host activity and reproduce with extensions disabled.

VS Code itself has a useful performance-debugging workflow worth studying. In particular, its performance guidance recommends collecting traces/profiles for renderer hangs and using verbose logging when investigating process/resource issues.

The VS Code source is also worth looking at around its diagnostics services. The Electron main-process startup code wires in DiagnosticsMainService, and VS Code exposes diagnostic/status functionality rather than treating the main process as an opaque Electron process.

So for a production application I'd aim for this incident bundle:

hang detected
    ↓
external watchdog records PID + timestamps
    ↓
event-loop lag / CPU / memory snapshot
    ↓
Node diagnostic report where supported
    ↓
OS-level dump where available
    ↓
application logs + recent IPC/request history
    ↓
correlate stacks with CPU/resource/IPC timeline
    ↓
classify: JS / sync I/O / native / IPC / OS / extension pressure

The key is to design the diagnostics before the hang occurs. Once the main event loop is blocked, anything that depends on that same event loop is inherently unreliable.

References:

• Node diagnostic reports: https://nodejs.org/api/report.html
• Electron main-process debugging: https://www.electronjs.org/docs/latest/tutorial/debugging-main-process
• Electron application debugging: https://www.electronjs.org/docs/latest/tutorial/application-debugging
• VS Code performance troubleshooting: https://github.com/microsoft/vscode/wiki/performance-issues
• VS Code Electron main process: https://github.com/microsoft/vscode/blob/main/src/vs/code/electron-main/main.ts****

[SKY ZHAO (skyzhao1223)]

The governing fact: a hung main process cannot report on itself. ipcMain, app.getAppMetrics(), a process-explorer window, menus, dialogs — and in a single-instance app even your own CLI — all route through main's one event loop. So hang diagnosis has exactly two shapes: tools that run outside the process, and channels you armed before the hang.

Everything below I verified against Electron 44.4.3 (Node v24.21.0) on macOS by actually wedging a main process, plus reading Node/Electron/VS Code source. Where I could only verify from source or docs, I say so.

1. Triage: which process is wedged

CPU posture plus the process tree settles most cases in seconds. The main process is the one with no --type= flag:

$ ps -eo pid,ppid,%cpu,command | grep Electron
75479 75474 99.7 .../MacOS/Electron .                    ← main ("Browser")
75480 75479  0.0 ... Helper... --type=gpu-process
75481 75479  0.0 ... Helper... --type=utility --utility-sub-type=network.mojom.NetworkService
75482 75479  0.0 ... Helper... --type=utility --utility-sub-type=node.mojom.NodeService

• main pegged ~100% of one core → JS spin (loop, giant JSON.parse, catastrophic regex, sync crypto)
• main at 0%, sleeping → blocked in native code: sync fs/exec/dialog, network mount, AV filter driver, native addon, or an invisible modal dialog
• only a renderer or utility pid busy → not a main hang

app.getAppMetrics() gives you the same data in-process (pid, type, serviceName, cpu.percentCPUUsage, memory.workingSetSize) but only while main still answers. Note percentCPUUsage is an average since the previous call, so the first call returns 0 — sample twice. Electron ships no Task-Manager UI; VS Code builds one (Open Process Explorer, and code --status via src/vs/platform/process/electron-main/processMainService.ts). Both are served by main — if they hang too, that confirms main is the wedged one.

2. JS stacks from a hung main: SIGUSR1 → inspector

Node arms its inspector on SIGUSR1 (port 9229). This is documented Electron behaviour, not an accident: the --inspect-port switch is described as "useful when activating the inspector by sending the SIGUSR1 signal", and the nodeCliInspect fuse (default Enabled) says that when disabled "SIGUSR1 signal does not initialize the main process inspector". The gate is in shell/common/node_bindings.cc, which sets kNoStartDebugSignalHandler only when that fuse is off.

Why it works on a loop that never returns: Node runs a dedicated SignalInspector watchdog thread. The signal handler only posts a semaphore (async-signal-safe); the watchdog then calls Agent::RequestIoThreadStart(), which does both env->RequestInterrupt(StartIoThread) — V8 interrupt checks fire constantly inside while(true) — and uv_async_send. The inspector then runs on its own thread, so you can pause and profile a main thread that never comes back to your code.

Demonstrated on a main process spinning at 99.7% CPU:

$ kill -USR1 75479
$ curl -s http://127.0.0.1:9229/json/list
[{"type":"node","url":"file:///private/tmp/el-hang",
  "webSocketDebuggerUrl":"ws://127.0.0.1:9229/5b05b398-…"}]

Then attach any CDP client (chrome://inspect, a VS Code attach config, node inspect 127.0.0.1:9229) and send Debugger.enable + Debugger.pause. Real output:

at (anonymous) (main.js:51:7)          ← the while(true) line, exact column
at listOnTimeout (node:internal/timers:685:17)
at processTimers (node:internal/timers:618:7)

Once attached you can read scope variables at the frozen frame and take a live CPU profile via Profiler.start/stop — unlike --cpu-prof, which only writes on exit.

Windows: no POSIX signals. The equivalent is process._debugProcess(pid) from another Node process — POSIX-wise it is literally kill(pid, SIGUSR1); on Windows it opens the target's node-debug-handler-<pid> shared mapping and CreateRemoteThreads the inspector start (node_process_methods.cc, inspector_agent.cc). node inspect -p <pid> does exactly this. VS Code ships the pattern: UtilityProcess.enableInspectPort() in src/vs/platform/utilityProcess/electron-main/utilityProcess.ts calls process._debugProcess(this.processPid), with a comment calling it the "(undocumented) _debugProcess feature of node". I verified it live on macOS against an Electron utilityProcess child; the Windows half is source-verified only.

The limit that matters — SIGUSR1 is inert when the thread is parked in native code. No JS runs, so RequestInterrupt never fires, and if the loop can't tick the uv_async path is dead too. I hit this for real: an Electron instance stuck in a native dialog.showErrorBox (from lib/browser/init.ts's uncaughtException handler) sat at 0% CPU in CFRunLoopRun → mach_msg, and two SIGUSR1 attempts never opened 9229. sample/lldb answered in seconds. Rule: SIGUSR1 gets you JS stacks for JS problems; native problems need native tools.

Also check the fuse on any third-party binary: npx @electron/fuses read --app "<path>". On the installed VS Code 1.100.3 it reports RunAsNode, EnableNodeOptionsEnvironmentVariable and EnableNodeCliInspectArguments all Enabled, so production VS Code keeps these channels live.

3. Native stacks

• macOS sample <pid> 5 -file /tmp/hang.txt — built in, no prompts on a user-owned app. On the busy-looped main it gave 1649/1649 samples in V8 JIT frames (raw addresses = "spinning in JS"); on the dialog-stuck instance, CFRunLoopRun → mach_msg. Module attribution is the killer feature: samples landing in your *.node addon or an AV driver identify the culprit with zero JS cooperation.
• macOS lldb -p <pid> → thread backtrace all. The main thread is named CrBrowserMain (renderers: CrRendererMain) — instant positive ID. Caveat: I only tested an ad-hoc-signed npm dist; hardened-runtime production builds may need get-task-allow or user approval.
• Linux gdb -p <pid> → thread apply all bt; gcore <pid> for a full core. (doc-verified, not run here.)
• Windows ProcDump: procdump.exe -accepteula -ma <pid> C:\dumps, and the one that fits your scenario — procdump.exe -accepteula -h -ma YourApp.exe C:\dumps, where -h writes a dump when a window has been unresponsive for 5 s (Task Manager's own definition). Pre-armed and automatic. Analyze with ~*k, !analyze -hang, !runaway. (doc-verified.)
• Crashpad (crashReporter.start(...)) is for crashes, not hangs — wire it up anyway, but hang dumps come from the watchdog or procdump. Electron uses Crashpad, not Breakpad; dumps land in <userData>/Crashpad unless you set app.setPath('crashDumps', …).

4. Node diagnostic reports — what actually works

• process.report.writeReport() works in the Electron main process (verified: report v5 with javascriptStack, nativeStack, libuv, …). Only useful pre-armed or fired while the loop can still tick.
• --report-on-signal (default SIGUSR2) is weaker than it looks: lib/internal/process/report.js implements it as process.on(sig, signalHandler), so it needs one loop iteration. On my busy-looped main, SIGUSR2 was caught (the process survived) but no report was written. Signal-based reports are also unsupported on Windows, and in Electron they ride NODE_OPTIONS → dev only.
• NODE_OPTIONS is explicitly disallowed in packaged apps except --max-http-header-size/--http-parser. Never build production diagnostics on it. --inspect/--inspect-brk do work packaged, iff the fuse is on.
• --cpu-prof writes before exit — a hung process you later kill -9 produces nothing. Use the live CDP Profiler instead.

5. What VS Code does, and the lesson worth copying

The entry point is src/main.ts (there is no src/main.js). The files worth reading:

Concern	File
argv, crashReporter.start, --crash-reporter-directory, --trace→contentTracing, --js-flags, enableSandbox()	src/main.ts
enableInspectPort() via process._debugProcess; child-process-gone telemetry	src/vs/platform/utilityProcess/electron-main/utilityProcess.ts
Shared process / extension host / pty host as utility processes	sharedProcess.ts, extensionHostStarter.ts, electronPtyHostStarter.ts
Heartbeat watchdog: 5 s beats, two-stage timeouts, capped auto-restart	src/vs/platform/terminal/node/heartbeatService.ts + ptyHostService.ts
Renderer-unresponsive JS-stack sampling (1000 ms interval / 15000 ms period, >20% duplicate stacks → telemetry) via frame.collectJavaScriptCallStack()	src/vs/platform/windows/electron-main/windowImpl.ts
--prof-startup: relaunches with three --inspect-brk ports and drives CDP profiles	src/vs/code/node/cli.ts
Every diagnostic flag	src/vs/platform/environment/node/argv.ts

The architectural point: VS Code's main process rarely hangs because it barely does anything. Windows, menus, dialogs, lifecycle, supervision — that's the job. Extensions, file watching, search and terminals all run in utilityProcess children (the API landed in Electron 22), extension host per window. A wedged extension stalls its own host, not the app; a crashed utility process is caught and restarted; the pty host additionally gets an application-level heartbeat.

If your main process hosts business logic today, moving it to utility processes and keeping main a thin supervisor is the highest-leverage change available — it converts "app hangs" into "one service hangs, detected by heartbeat, auto-restarted." Pair it with an out-of-process watchdog that pings main every N seconds and, on missed pings, auto-collects evidence (_debugProcess + CDP on POSIX, procdump -ma on Windows, sample on macOS) before restarting. VS Code doesn't watchdog its own main — nothing left inside main could report it — but you can, because you own the child.

6. Runbook

0. Posture (any OS, zero risk). Find the pid with no --type= and read its CPU. Pegged → step 2. Idle → step 1 then 3.

1. OS sampling — works even when the thread is natively blocked:

sample <pid> 5 -file /tmp/hang.txt                      # macOS
gdb -p <pid> -batch -ex 'thread apply all bt'           # Linux
procdump.exe -accepteula -h -ma YourApp.exe C:\dumps    # Windows (auto on 5 s hang)

2. JS stacks via inspector (POSIX; needs JS executing or the loop ticking; needs the nodeCliInspect fuse):

kill -USR1 <pid>
curl -s http://127.0.0.1:9229/json/list    # target appears within ~1 s
# attach → Pause → exact stack; optionally Profiler.start for a live profile

Windows, or scripted anywhere: process._debugProcess(<pid>) from a separate Node process (equivalently node inspect -p <pid>).

3. Native attach when step 2 stays dark, or for module attribution: lldb -p / gdb -p / WinDbg on the procdump .dmp. Read CrBrowserMain: V8/JIT frames → JS problem (symbolize via step 2); read/wait4/mach_msg/kernel frames → identify the resource; frames inside *.node or a filter driver → addon or AV.

4. Pre-arm for next time: an out-of-process watchdog; an in-main lag monitor (perf_hooks.monitorEventLoopDelay()); crashReporter.start() on main's first line; a --trace switch wired to contentTracing; lint-ban *Sync APIs in main-process code.

If the frozen app is VS Code itself: code --status and Help → Open Process Explorer (both hang too if main is wedged — itself evidence); --crash-reporter-directory /tmp/x for local dumps; --trace --trace-category-filter="renderer,blink,v8,disabled-by-default-v8.cpu_profiler" then "Developer: Stop Tracing" for unresponsive windows; --inspect-extensions=5870, --inspect-sharedprocess (5879), --inspect-ptyhost (5877); --prof-startup for startup profiles. Recipes: https://github.com/microsoft/vscode/wiki/Runtime-debugging

---

Runtime claims were demonstrated on macOS (arm64), Electron 44.4.3 / Node v24.21.0, against a minimal app wedged with while(true){}. Windows and Linux command syntax is quoted from Microsoft/GNU docs and Node/Electron source but was not executed here. VS Code claims were read at microsoft/vscode main @ aca2ff4f.

[Joel (aspire488)]

This is a really useful distinction, especially the separation between JS-level inspection and native-level inspection.
The SIGUSR1 caveat is probably the most important part for anyone building a production Electron diagnostic workflow. Treating it as a universal “attach to a hung process” mechanism would give a false sense of coverage when the main thread is actually parked in native code.
I also like the distinction between diagnostics that require the main event loop and diagnostics that remain viable when that loop is dead. It suggests a fairly clean production design:
main process → heartbeat/telemetry → external watchdog → OS-level capture
with the inspector, tracing, and process.report acting as richer secondary channels when the process is still responsive enough to service them.
The VS Code architecture is particularly interesting here. Moving expensive or failure-prone work into utility/shared processes doesn't just improve responsiveness — it changes what can be diagnosed when something goes wrong. The main process becomes less of a single point of failure.
One thing I'd be interested in seeing explored further is the decision logic for an automated watchdog: how you distinguish “main event loop is genuinely wedged” from a legitimate long-running operation, and when you escalate from heartbeat loss → inspector attempt → native dump. That seems like the piece that could turn these techniques into a reusable production diagnostic subsystem rather than just a collection of debugging tools.