[BUG] Claude Code 2.1.15 crashes with "Illegal instruction" on virtualized environments lacking AVX CPU support (Bun runtime requirement)

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Description

Claude Code 2.0.15 crashes immediately on startup with an "Illegal instruction" panic when running on virtual machines that do not expose AVX CPU instructions. This is a breaking change from previous versions that used Node.js, as the new Bun runtime requires AVX support.

Environment

• Claude Code Version: 2.0.15
• OS: Linux (Debian-based, kernel 6.12.57)
• Virtualization: Proxmox VE with QEMU/KVM
• CPU Configuration: Default QEMU virtual CPU (does not expose AVX)

Error Output

============================================================
Bun v1.3.6 (d530ed99) Linux x64 (baseline)
Linux Kernel v6.12.57 | glibc v2.41
CPU: sse42 popcnt
Args: "claude"
Features: Bun.stderr(2) Bun.stdin(2) Bun.stdout(2) fetch(29) jsc no_avx2 no_avx spawn(20) standalone_executable
Builtins: "bun:main" "node:assert" "node:async_hooks" "node:buffer" "node:child_process" "node:constants" "node:crypto" "node:domain" "node:events" "node:fs" "node:fs/promises" "node:http" "node:https" "node:module" "node:net" "node:os" "node:path" "node:path/posix" "node:path/win32" "node:perf_hooks" "node:process" "node:querystring" "node:stream" "node:timers/promises" "node:tls" "node:tty" "node:url" "node:util" "node:zlib" "node:worker_threads" "undici" "ws" "node-fetch" "node:inspector" "node:http2" "node:diagnostics_channel"
Elapsed: 2882ms | User: 3646ms | Sys: 1240ms
RSS: 1.18GB | Peak: 0.44GB | Commit: 1.18GB | Faults: 0 | Machine: 16.78GB

CPU lacks AVX support. Please consider upgrading to a newer CPU.
panic(main thread): Illegal instruction at address 0x4001FB4
oh no: Bun has crashed. This indicates a bug in Bun, not your code.

Root Cause Analysis

Summary: The migration from Node.js to Bun runtime in Claude Code 2.0.15 introduced a hard dependency on AVX (Advanced Vector Extensions) CPU instructions, which are not exposed by default in many virtualized environments.

Technical Details:

1. Runtime Change: Claude Code 2.0.15 switched from Node.js to Bun as its JavaScript runtime
2. Bun's AVX Requirement: Bun's JavaScript engine (JavaScriptCore) uses AVX instructions for performance optimizations and crashes when these are unavailable
3. Virtualization Impact: Common hypervisors (QEMU/KVM, VirtualBox, VMware) often use generic CPU models by default that don't expose AVX flags to guest VMs
4. Breaking Change: Previous Node.js-based versions worked without AVX support

Why This Happens in VMs:

• Default QEMU CPU types like qemu64 or kvm64 only expose baseline x86-64 instructions
• AVX support requires either:
• Passing through the host CPU type (-cpu host)
• Using a CPU model that includes AVX (e.g., SandyBridge, Haswell, or newer)

Resolution / Workaround

For Proxmox/QEMU users:

1. Shut down the VM
2. Edit the VM configuration to use host CPU passthrough:

• In Proxmox UI: VM → Hardware → Processor → Type → Select "host"
• Or via CLI: qm set <vmid> -cpu host

1. Start the VM

For other hypervisors:

• VirtualBox: Ensure "Enable Nested VT-x/AMD-V" is enabled and use a modern CPU profile
• VMware: Use "Virtualize Intel VT-x/EPT or AMD-V/RVI" option

Verified Working: After changing the CPU type to host, Claude Code 2.0.15 launches successfully.

Check AVX availability:

grep -o 'avx[^ ]*' /proc/cpuinfo | head -1
# Should output: avx avx2 (or similar)

Suggested Improvements

1. Documentation Update: Add a note about AVX CPU requirements to the installation documentation
2. Graceful Error Handling: If possible, detect AVX support and provide a clearer error message before Bun crashes
3. Consider Baseline Build: Bun offers a baseline build without AVX requirements that could be used as a fallback (though with reduced performance)

Impact

This issue affects users running Claude Code in:

• Proxmox VE with default CPU settings
• QEMU/KVM virtual machines
• Older cloud instances without AVX
• Any x86-64 environment without AVX support

Related

• Bun requires AVX support on x86-64: Bun's JavaScriptCore engine uses AVX instructions
• Bun does provide baseline builds without AVX requirements, though the standalone executable bundled with Claude Code appears to use the standard build

What Should Happen?

Claude Code should either:

1. Launch successfully on systems without AVX support (using a baseline Bun build), or
2. Provide a clear, user-friendly error message explaining the AVX requirement and how to resolve it in virtualized environments, rather than crashing with a Bun panic

Error Messages/Logs

============================================================
Bun v1.3.6 (d530ed99) Linux x64 (baseline)
Linux Kernel v6.12.57 | glibc v2.41
CPU: sse42 popcnt
Args: "claude"
Features: Bun.stderr(2) Bun.stdin(2) Bun.stdout(2) fetch(29) jsc no_avx2 no_avx spawn(20) standalone_executable
Builtins: "bun:main" "node:assert" "node:async_hooks" "node:buffer" "node:child_process" "node:constants" "node:crypto" "node:domain" "node:events" "node:fs" "node:fs/promises" "node:http" "node:https" "node:module" "node:net" "node:os" "node:path" "node:path/posix" "node:path/win32" "node:perf_hooks" "node:process" "node:querystring" "node:stream" "node:timers/promises" "node:tls" "node:tty" "node:url" "node:util" "node:zlib" "node:worker_threads" "undici" "ws" "node-fetch" "node:inspector" "node:http2" "node:diagnostics_channel"
Elapsed: 2882ms | User: 3646ms | Sys: 1240ms
RSS: 1.18GB | Peak: 0.44GB | Commit: 1.18GB | Faults: 0 | Machine: 16.78GB

CPU lacks AVX support. Please consider upgrading to a newer CPU.
panic(main thread): Illegal instruction at address 0x4001FB4
oh no: Bun has crashed. This indicates a bug in Bun, not your code.

Steps to Reproduce

1. Create a Linux VM in Proxmox (or other QEMU/KVM hypervisor) using the default CPU type (e.g., kvm64 or qemu64)
2. Install Claude Code 2.0.15 via npm: npm install -g @anthropic-ai/claude-code
3. Run claude in the terminal
4. Observe the Bun crash with "Illegal instruction" panic

Claude Model

None

Is this a regression?

Yes, this worked in a previous version

Last Working Version

2.0.12

Claude Code Version

2.0.15

Platform

Anthropic API

Operating System

Ubuntu/Debian Linux

Terminal/Shell

VS Code integrated terminal

Additional Information

_No response_