Debugging and Troubleshooting Common Electron Issues

When your Electron app crashes, hangs, or consumes excessive memory, finding the root cause quickly matters. This guide provides practical debugging techniques for the most common Electron issues, focusing on what to check first and which tools to use.

Diagnosing Renderer Process Crashes and Hangs

Quick Checks for Renderer Issues

When a renderer process crashes or becomes unresponsive, start with these immediate checks:

1. Open DevTools programmatically before the crash occurs:

win.webContents.openDevTools({ mode: 'detach' });

2. Check the console for uncaught exceptions - Most renderer crashes stem from unhandled JavaScript errors.

3. Monitor memory usage via Chrome DevTools Performance tab - Look for memory spikes before crashes.

Debugging Renderer Process with DevTools

For persistent renderer issues:

• Enable crash reporting: Add win.webContents.on('crashed', (event) => {}) to capture crash events
• Use memory snapshots: Take heap snapshots in DevTools (Memory tab) to identify leaking objects
• Disable hardware acceleration for testing: app.disableHardwareAcceleration() - eliminates GPU-related crashes

Quick verification: If the issue disappears with hardware acceleration disabled, you’ve isolated a GPU problem.

Debugging Main Process Issues

VS Code Electron Debugging Setup

Configure VS Code for main process debugging with this minimal launch.json:

{
  "type": "node",
  "request": "launch",
  "name": "Debug Main Process",
  "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron",
  "program": "${workspaceFolder}/main.js",
  "outputCapture": "std"
}

Main Process Troubleshooting

First steps for main process issues:

1. Check stdout/stderr: Add "outputCapture": "std" to see native module errors
2. Set breakpoints in lifecycle events (app.on('ready'), app.on('before-quit'))
3. Monitor process memory: Use process.memoryUsage() to log RSS values

Remediation approaches:

• For high RSS: Check for retained BrowserWindow references - ensure win = null after close
• For crashes: Enable core dumps with app.setPath('crashDumps', path)
• For hangs: Profile CPU usage with --inspect flag and Chrome DevTools

Memory Leaks and High RSS

Electron Memory Profiling Techniques

Identify memory leaks systematically:

1. Compare heap snapshots: Take snapshots before and after suspected leak operations
2. Monitor RSS vs heap: RSS includes native memory - if RSS grows but heap doesn’t, check native modules
3. Track IPC listeners: Unregistered listeners are common leak sources

IPC Listener Leak Prevention

Common IPC memory leak pattern:

// BAD: Creates new listener each render
ipcRenderer.on('data-update', handler);

// GOOD: Remove on unmount
const handler = (event, data) => { /* ... */ };
ipcRenderer.on('data-update', handler);
// On cleanup:
ipcRenderer.removeListener('data-update', handler);

Verification: Check listener count with ipcRenderer.listenerCount('event-name')

Configuration and Security Issues

Debug Mode Exposure Prevention

Critical production checks:

1. Disable DevTools in production:

if (app.isPackaged) {
  win.webContents.on('devtools-opened', () => {
    win.webContents.closeDevTools();
  });
}

2. Remove debug menu items: Strip debug options from production menus
3. Disable remote module: Set enableRemoteModule: false in webPreferences

When to Escalate

Create a minimal reproduction before filing issues:

1. Isolate the problem: Remove all non-essential code
2. Test with vanilla Electron: Use minimal-repro as baseline
3. Document precisely: Include exact RSS/heap numbers, Electron version, and platform

When filing Electron/Chromium issues, provide:

• Minimal reproducible code
• Memory measurements (RSS and heap)
• Process type affected (main/renderer)
• Crash dumps if available

Best Practices

Three Essential Debugging Practices

1. Secure production builds: Always check app.isPackaged before enabling debug features. Never ship with DevTools accessible.

2. Clean up IPC listeners: Implement a cleanup pattern for all IPC listeners. Use removeListener() or removeAllListeners() on component unmount.

3. Monitor RSS alongside heap: JavaScript heap snapshots don’t show native memory. Always track process.memoryUsage().rss for complete memory investigation.

Final tip: For complex debugging scenarios, use electron-debug to add DevTools shortcuts and other debugging features with minimal setup.

Conclusion

Debugging Electron applications requires a systematic approach to identify whether issues originate in the main or renderer process. By using the right tools—from DevTools for renderer issues to VS Code debugging for main process problems—you can quickly isolate and fix crashes, memory leaks, and performance issues. Remember to always secure your production builds and maintain clean IPC communication patterns to prevent common problems from occurring in the first place.

FAQs

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.