Fix Claude Code Bun Crash

Written by Michael Lip · Solo founder of Zovo · $400K+ on Upwork · 100% JSS Join 50+ builders · More at zovo.one

Last updated: April 17, 2026

Claude Code can crash when running under the Bun runtime due to memory limits, incompatible native modules, or Bun-specific bugs. This guide covers the most common Bun crash scenarios and how to fix each one.

The Problem

You are using Claude Code and it crashes with a Bun-related error, or Bun itself segfaults during Claude Code operations. The crash may appear as bun has crashed, a segfault, or an out-of-memory kill. This disrupts your workflow and can cause lost work if Claude Code was mid-edit.

Quick Solution

Step 1: Check your Bun version. Claude Code requires a recent Bun release:

bun --version

If you are below version 1.1, upgrade:

curl -fsSL https://bun.sh/install | bash

Step 2: If Claude Code crashes with an out-of-memory error, increase the Bun memory limit:

BUN_JSC_FORCE_RAM_SIZE=8192 claude

This sets the JSC (JavaScriptCore) heap limit to 8GB.

Step 3: If the crash is a segfault (signal 11), clear the Bun module cache:

rm -rf ~/.bun/install/cache
bun install

Step 4: If the crash persists, try running Claude Code with Node.js instead of Bun as a diagnostic step:

which node
node --version

If Claude Code works under Node.js but not Bun, the issue is Bun-specific. File a bug at github.com/oven-sh/bun/issues.

Step 5: Check if a specific native module is causing the crash. Run with verbose output:

BUN_DEBUG_QUIET_LOGS=0 claude 2>&1 | tee /tmp/claude-bun-debug.log

Review the log for the module that triggers the crash.

How It Works

Claude Code is a Node.js application that can run under Bun as an alternative JavaScript runtime. Bun uses JavaScriptCore (JSC) instead of V8, which means native Node.js modules need Bun-compatible bindings. When a module uses Node-API (napi) bindings that Bun has not fully implemented, or when JSC’s garbage collector behaves differently under heavy allocation patterns, crashes can occur. Claude Code is particularly memory-intensive because it holds conversation context, file contents, and tool results in memory simultaneously. Bun’s default memory ceiling can be lower than what Claude Code needs for large codebases.

Common Issues

Bun version too old. Bun’s Node.js compatibility improves rapidly between releases. Many crashes that occur on Bun 1.0.x are fixed in 1.1+. Always use the latest stable release.

Native module incompatibility. Some npm packages used by Claude Code’s dependencies rely on Node.js-specific native bindings that Bun does not fully support. If the crash log shows a specific .node file, that module is the culprit. You may need to fall back to Node.js until Bun adds support.

System-level OOM killer. On Linux with limited RAM (e.g., 4GB VPS), the OS OOM killer may terminate Bun before it can handle the error gracefully. Monitor with dmesg | tail after a crash to see if the kernel killed the process.

Example CLAUDE.md Section

# Bun Runtime Configuration

## Runtime
- Using Bun as JavaScript runtime
- Minimum Bun version: 1.1.0
- Memory limit set via BUN_JSC_FORCE_RAM_SIZE=8192

## Known Issues
- Large file reads (>2MB) can spike memory — use line-range reads instead
- If Bun crashes during install, fall back to: bun install --no-cache
- Native modules: esbuild, lightningcss work; node-gyp modules may not

## Crash Recovery
- If a crash occurs mid-edit, check git status for uncommitted changes
- Claude Code auto-saves aren't guaranteed during crashes — commit often
- Debug crashes with: BUN_DEBUG_QUIET_LOGS=0 claude 2>&1 | tee debug.log

Best Practices

Commit before complex operations. Before asking Claude Code to refactor multiple files, commit your current state. If Bun crashes mid-operation, you can restore cleanly.
Keep Bun updated. Run bun upgrade weekly. Bun’s compatibility and stability improve significantly with each release.
Set memory limits explicitly. Do not rely on Bun’s defaults. Export BUN_JSC_FORCE_RAM_SIZE in your shell profile to ensure consistent behavior.
Use Node.js as a fallback. If a Bun crash blocks your work, switch to Node.js temporarily. The functionality is identical — only the runtime differs.
Report crashes to the Bun team. Bun is actively developed and the team is responsive to crash reports. Include the Bun version, OS, and a minimal reproduction.

I'm a solo developer in Vietnam. 50K Chrome extension users. $500K+ on Upwork. 5 Claude Max subscriptions running agent fleets in parallel. These are my actual CLAUDE.md templates, orchestration configs, and prompts. Not a course. Not theory. The files I copy into every project before I write a line of code. **[See what's inside →](https://zovo.one/lifetime?utm_source=ccg&utm_medium=cta-default&utm_campaign=claude-code-bun-crash)** $99 once. Free forever. 47/500 founding spots left.