Bun Breaks npm Packages in Weird Ways

Been dealing with Bun compatibility bullshit for a while now. Here's the stuff that actually breaks in production, not the theoretical crap in the docs.

Package Resolution Hell

📦 Module Resolution Differences: Node.js vs Bun
Node.js follows CommonJS resolution while Bun uses ESM-first resolution with different fallback behaviors.

The most annoying shit isn't speed - it's packages that work fine in Node but Bun can't find. Happens because Bun's module resolution is different and package authors never test with Bun. Error messages are useless and tell you nothing.

Module resolution differs significantly between runtimes - Node.js uses CommonJS resolution algorithm while Bun implements ESM-first resolution. This creates incompatibilities with packages that rely on Node-specific resolution behaviors. The ECMAScript modules specification doesn't fully cover all edge cases that npm packages exploit.

exports field fucks everything up:

Modern packages use the "exports" field for module resolution. Node and Bun handle this differently:

Error: Cannot resolve "."/lib/index.js" from "."/node_modules/some-package/package.json"

Packages that break:

• @aws-sdk packages: Export maps don't match - AWS SDK v3 compatibility tracking
• Prisma client: Conditional exports fail - Prisma Bun support tracking
• GraphQL tools: Module resolution conflicts - GraphQL-tools compatibility issue
• Styled-components: Babel stuff breaks - styled-components Bun compatibility issue

Quick Fix - Check exports field:

bun pm ls | grep -A5 "."some-package"
cat node_modules/some-package/package.json | grep -A10 '"exports"'

Fix:

// Instead of this (breaks in Bun)
import { something } from 'package-name';

// Do this
import { something } from 'package-name/lib/something.js';

Native Modules Don't Work

⚠️ Native Module Compilation Failures
C++ addons compiled for Node.js N-API don't work with Bun's runtime

Native modules don't work in Bun. These packages compile C++ code that only works with Node. Error messages are garbage and Google won't help.

Why native modules fail: Node.js Native Addons use N-API which is Node-specific. Bun doesn't implement N-API and instead provides Bun's FFI system for native code integration. Node-gyp compilation fails because Bun runtime headers differ from Node.js headers.

Packages that break:

• sharp: Image processing - fails with "."Cannot find module '@img/sharp-libvips'"" - Sharp Bun compatibility status
• bcrypt: Password hashing - compilation errors or segfaults - bcrypt.js Bun tracking issue
• sqlite3: Database driver - use bun:sqlite instead
• node-canvas: Canvas API - no Bun version - Canvas alternatives for Bun
• fsevents: File watching - macOS native code breaks - Bun's built-in file watcher

Works in dev, breaks in prod:

Development on macOS might work with native modules, but production Docker containers will fail:

## This will break in production
FROM oven/bun:1.2-slim
RUN bun install sharp  # Fails: no pre-built binaries for Bun runtime

Solution:

1. Audit native modules first:

## Find all native modules in your project
find node_modules -name "."*.node"" -exec ls -la {} \;
grep -r "."node-gyp\\|binding\\.gyp"" node_modules/*/package.json

2. Use alternatives:

// Instead of bcrypt
import { hash } from 'bun';

// Instead of sqlite3
import { Database } from 'bun:sqlite';

// Instead of sharp
// Use ImageMagick in separate container

3. Split services:

## docker-compose.yml
version: '3.8'
services:
  api:
    image: oven/bun:1.2-slim
    command: bun run start

  image-processor:
    image: node:20-alpine
    command: npm run image-service

CPU Architecture Problems

💻 CPU Requirements: AVX2 Instructions
Bun requires modern CPU features that older servers lack, causing immediate crashes

Bun needs newer CPU instructions that older servers don't have. Crashes instantly with useless error messages.

AVX2 requirement details: Bun requires AVX2 CPU instructions for JavaScriptCore's JIT compiler. AWS EC2 instance types and Intel CPU generations affect compatibility. Azure VM sizes have similar limitations with older SKUs.

The Failure Pattern:

./bun: Illegal instruction (core dumped)

Happens on:

• AWS EC2 t2/t3 instances (older Xeon processors)
• Docker on old hosts
• CircleCI, older GitHub Actions runners
• Hardware from before 2013-2014

Check first:

## Check if CPU supports AVX2
grep -o 'avx2' /proc/cpuinfo | head -1

## If no AVX2 support, you're fucked - stick with Node.js

Spent 3 hours debugging this garbage "."Illegal instruction"" error. Turns out the EC2 instance was too old for Bun. Fix: get newer hardware or go back to Node. No software workaround exists.

Memory Leaks (JSC vs V8)

🧠 JavaScript Engine Differences
JavaScriptCore (Bun) vs V8 (Node.js) handle garbage collection and memory management differently

Bun uses JavaScriptCore instead of V8, so memory works differently. Stuff that got cleaned up fine in Node just sits around eating memory.

GC differences matter: JavaScriptCore uses different garbage collection than V8's generational collection. Memory pressure handling differs between engines. JSC heap snapshots use different format than V8 heap profiling.

What leaks memory:

• Closure-heavy code (objects live longer in JSC)
• Event listeners without cleanup
• Large object caching (different GC timing)
• Async iteration (generators behave differently)

Debug Memory Issues:

import { heapStats } from 'bun:jsc';

// Monitor memory every 30 seconds
setInterval(() => {
  const stats = heapStats();
  const memMB = Math.round(stats.heapSize / 1024 / 1024);

  if (memMB > 500) { // Not sure what's normal tbh
    console.error(`Memory leak warning: ${memMB}MB heap`);
    process.writeHeapSnapshot?.(`leak-${Date.now()}.heapsnapshot`);
  }
}, 30000);

Don't do this:

app.get('/api/data', (req, res) => {
  const largeData = loadMassiveDataset(); // Leaked in closure

  return processRequest(req, (result) => {
    res.json(result); // Closure keeps largeData alive
  });
});

Do this:

app.get('/api/data', (req, res) => {
  const result = processRequestSync(req);
  res.json(result);
});

Windows Problems

Windows support exists but comes with weird failures that Linux/macOS devs never see.

File Permission Failures:

## Common Windows error
error: Access denied, EACCES
  path: "."node_modules/.bin/some-command"

Why it breaks:

• Windows Defender thinks fast file operations = malware
• NTFS permission issues with symlinks
• PATH length limits (260 chars) break deep node_modules
• PowerShell execution policy blocks scripts

Windows-Specific Fixes:

## 1. Allow PowerShell script execution
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

## 2. Enable long path support (requires admin - good luck)
New-ItemProperty -Path "."HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem"" -Name "."LongPathsEnabled"" -Value 1 -PropertyType DWORD -Force

## 3. Exclude project directory from Windows Defender (sometimes works)
Add-MpPreference -ExclusionPath "."C:\dev\your-project""

Better: Use WSL2

## Install Bun in WSL2 instead
curl -fsSL https://bun.sh/install | bash

Windows support exists but you'll hate your life. Sometimes Windows Defender thinks Bun is malware because it does file operations fast. Use WSL2 to avoid the Windows bullshit.

Latest Shell Crashes

Bun 1.2.21 has new crash when running some shell commands on Windows. Running `cds build --production` causes null pointer panic in shell event loop.

The Pattern:

## This crashes Bun 1.2.21 on Windows
bun run cds build --production

## Stack trace shows
panic: attempt to use null value
* EventLoopHandle.zig:133: topLevelDir

Workaround:

## Use npm run instead
npm run build

## Or downgrade until fixed
bun --version # Check if you're on 1.2.21

This affects SAP CAP framework users, but indicates broader shell command instability. Another reason to have Node.js fallback ready.

Been running Bun in production and debugging the weird shit that breaks. Issues that will kill your deployment.

Docker Containers Die with Exit 143

🐋 Container Signal Handling Problem
Exit code 143 = SIGTERM not properly handled by Bun process

Most common production failure isn't code - containers randomly die with exit code 143. Took forever to figure out it was signal handling. Logs tell you nothing.

Signal handling context: Docker exit code 143 means SIGTERM but Bun process management differs from Node.js. Docker signal propagation requires process initialization for proper cleanup. Kubernetes pod termination follows same patterns.

The Problem:
Docker sends SIGTERM to gracefully shut down containers, but Bun doesn't receive the signal properly without the --init flag. Container gets killed hard after timeout.

## Container logs show this and nothing else
Process exited with code 143

Why this sucks:

• Database connections don't close properly
• In-flight requests get killed mid-processing
• App state gets corrupted
• Health checks start failing randomly

Fix:

## WRONG - causes random deaths
CMD ["bun", "run", "start"]

## RIGHT - proper signal handling
CMD ["bun", "--init", "run", "start"]

## Alternative
RUN apk add --no-cache tini
ENTRYPOINT ["/sbin/tini", "--"]
CMD ["bun", "run", "start"]

This broke our staging environment for 2 days - containers dying every 10-15 minutes under load. Spent 6 hours digging through useless logs. Adding --init fixed it but nobody mentions this shit in the deployment docs.

Environment Variables Break

⚙️ Environment Variable Loading Differences
Bun auto-loads .env files while Node.js requires dotenv package

Bun handles environment variables differently than Node in ways that break config loading.

Env loading differences: Bun automatically loads .env files unlike Node.js requiring dotenv. Environment variable timing differs between runtimes. Process.env initialization happens at different lifecycle points.

process.env timing issues:

// This pattern breaks in Bun
const config = {
  port: process.env.PORT || 3000,
  database: process.env.DATABASE_URL
};

// Environment variables aren't available immediately
console.log(config.database); // undefined in Bun

Bun pattern:

// Correct pattern for Bun
import { env } from 'bun';

const config = {
  port: env.PORT || 3000,
  database: env.DATABASE_URL
};

// Or load .env files first
await import('./env-loader.js');

.env File Loading Differences:

// Node.js
require('dotenv').config();

// Bun (no dotenv needed, but timing differs)
// Loads .env automatically

Memory Allocation Patterns That Kill Performance

📊 Memory Management Patterns
JSC memory patterns differ from V8, causing unexpected memory pressure in production

Bun's memory management creates different pressure points than Node.js. Code that ran fine in Node can cause memory spikes in production.

Memory pattern differences: JSC garbage collection behavior differs from V8 memory management. Production memory monitoring requires different tooling than Node.js. Container memory limits affect OOM behavior differently in Bun.

Request Handler Memory Accumulation:

// This pattern leaks memory in Bun
const requestCache = new Map();

app.get('/api/*', (req, res) => {
  // Map grows forever in JSC - different GC timing
  requestCache.set(req.url, { timestamp: Date.now(), response: data });

  // In Node: GC cleans this regularly
  // In Bun: References persist longer, causing OOM
});

Memory-Safe Patterns for Bun:

// Use WeakMap for request-scoped caching
const requestCache = new WeakMap();

// Or implement explicit cleanup (this usually works, but sometimes...)
const requestCache = new Map();
setInterval(() => {
  const cutoff = Date.now() - 300000; // 5 minutes
  for (const [key, value] of requestCache) {
    if (value.timestamp < cutoff) {
      requestCache.delete(key);
    }
  }
}, 60000); // Clean every minute

Monitoring Memory in Production:

// Set up memory monitoring before problems occur
import { heapStats } from 'bun:jsc';

const logMemoryStats = () => {
  const stats = heapStats();
  const rss = process.memoryUsage.rss();

  console.log({
    timestamp: new Date().toISOString(),
    heap_mb: Math.round(stats.heapSize / 1024 / 1024),
    rss_mb: Math.round(rss / 1024 / 1024),
    heap_objects: stats.objectCount
  });

  // Alert if memory is growing dangerously
  if (rss > 800 * 1024 * 1024) { // 800MB works for our API server - adjust for your setup
    console.error('Memory usage critical - investigate memory leaks');
    // In production, we restart containers at 1GB to prevent OOM kills
  }
};

setInterval(logMemoryStats, 30000);

File System and I/O Failures

Bun's file system APIs have edge cases that don't exist in Node.js, particularly around file permissions and concurrent access.

File Permission Edge Cases:

// This works in Node.js but fails in Bun on some systems
import fs from 'fs';
fs.writeFileSync('/tmp/cache.json', data); // Permission denied

// Bun-specific file operations
import { write } from 'bun';
await write('/tmp/cache.json', data); // Different permission handling

Concurrent File Access Issues:

// Multiple processes accessing same file cause different errors
// Node.js: Graceful file locking
// Bun: Immediate failure or corruption

// Safe pattern for Bun
import { Database } from 'bun:sqlite';
const db = new Database('/tmp/cache.db');
// SQLite handles concurrent access better than JSON files

Network and HTTP Client Differences

Bun's HTTP client behaves differently from Node.js in timeout handling and connection pooling.

Timeout Behavior Changes:

// Node.js HTTP timeouts work differently than Bun fetch()
const response = await fetch('https://api.example.com/data', {
  timeout: 5000 // This doesn't work the same way
});

// Bun-specific timeout handling
const controller = new AbortController();
setTimeout(() => controller.abort(), 5000);

const response = await fetch('https://api.example.com/data', {
  signal: controller.signal
});

Connection Pool Exhaustion:

// Bun's fetch() uses different connection pooling
// Can exhaust connections faster than Node.js

// Monitor connection usage
const activeConnections = new Set();

async function makeRequest(url) {
  const id = Math.random().toString(36);
  activeConnections.add(id);

  try {
    const response = await fetch(url);
    return response;
  } finally {
    activeConnections.delete(id);

    if (activeConnections.size > 100) {
      console.warn(`High connection count: ${activeConnections.size}`);
    }
  }
}

DNS Resolution and Network Stack Issues

Production environments often have DNS caching and custom resolution that Bun handles differently.

Corporate Network Problems:

// Bun doesn't respect some DNS resolution settings
// that Node.js handles automatically

// Check DNS resolution explicitly
try {
  const response = await fetch('https://internal.company.com/api');
} catch (error) {
  if (error.cause?.code === 'ENOTFOUND') {
    console.error('DNS resolution failed - check network config');
    // Fallback to IP address or different endpoint
  }
}

Load Balancer Health Check Failures:

// Health check endpoints need special handling in Bun
app.get('/health', (req, res) => {
  // Bun's response timing differs from Express/Node
  // Health checks might timeout even when app is healthy

  const healthData = {
    status: 'ok',
    timestamp: Date.now(),
    uptime: process.uptime(),
    memory: process.memoryUsage.rss()
  };

  // Ensure response is sent immediately
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify(healthData));
});

Error Handling and Logging Differences

Production error tracking works differently in Bun, affecting debugging and monitoring.

Stack Trace Differences:

// Error stack traces show different information
try {
  problematicFunction();
} catch (error) {
  // Bun stack traces include different frame information
  // Some APM tools don't parse them correctly
  console.error('Full error context:', {
    message: error.message,
    stack: error.stack,
    cause: error.cause,
    // Include Bun-specific runtime info
    runtime: 'bun',
    version: process.versions.bun
  });
}

APM Integration Issues:

// Some monitoring tools expect Node.js-specific APIs
// that don't exist in Bun

// Ensure APM compatibility
if (typeof process.versions.bun !== 'undefined') {
  console.log('Running on Bun - some APM features may not work');
  // Use Bun-compatible monitoring approach
}

Look, Bun production deployments will bite you in the ass in ways nobody documents. I've learned to budget 3x the time for debugging weird runtime differences that don't exist in Node. You've been warned.

When Bun production deployments fail, they fail hard. How to diagnose and recover when your app is down.

Immediate Triage

🚨 Production Failure Patterns
Bun failures follow predictable signatures - identify the pattern quickly

Production Bun failures fall into predictable patterns. Figure out which one you're dealing with.

Production debugging resources: Kubernetes troubleshooting guide applies to Bun containers. Docker debugging techniques work with container log analysis. Production monitoring strategies help with Bun-specific metrics.

Container Death Pattern (Exit 143):

## Check container logs
docker logs container-name | tail -20

## Look for this pattern
Process exited with code 143

Fix: Add --init flag and redeploy. Recovery: 5 minutes if lucky, 20 minutes if CI is slow.

Native Module Pattern:

## Look for these error signatures
Error: Cannot find module '@img/sharp-libvips-linux-x64'
Error: Module did not self-register

Fix: Rollback to Node or remove native dependencies. Recovery: 15-30 minutes if rollback doesn't break something else.

Memory Exhaustion Pattern:

## Check memory usage
docker stats container-name

## Look for memory climbing to container limit
## Then sudden container restart

Fix: Restart containers, increase memory limits. Recovery: 2-5 minutes.

CPU Architecture Mismatch:

## Log pattern
./bun: Illegal instruction (core dumped)

Fix: Deploy to compatible hardware or rollback to Node. Recovery: 30+ minutes and explaining to management.

Emergency Rollback Strategies

🔄 Rollback Decision Matrix
Docker tag rollback (2-5 min) → Feature flags (10 min) → Partial service rollback (15+ min)

When Bun deployment is completely fucked and your boss is asking why the site is down, you need fast rollback options.

Rollback best practices: Kubernetes deployment rollbacks provide automated recovery mechanisms. Docker image versioning enables quick container swaps. Blue-green deployment patterns reduce rollback time.

Docker Tag Rollback (Fastest):

## Roll back to previous Node.js image
kubectl set image deployment/api-server api=your-app:node-v1.2.3

## Or with docker-compose
docker-compose up -d --scale api=0 && \
docker-compose -f docker-compose.node.yml up -d api

Feature Flag Rollback (If Available):

// Runtime switching between Bun and Node.js
const runtime = process.env.USE_BUN === 'true' ? 'bun' : 'node';

if (runtime === 'node') {
  // Fallback to Node.js implementation
  exec('node server.js');
} else {
  // Try Bun implementation
  exec('bun --init run start');
}

Partial Rollback (Service-by-Service):

## Kubernetes deployment - roll back critical services first
apiVersion: apps/v1
kind: Deployment
metadata:
  name: payment-service
spec:
  template:
    spec:
      containers:
      - name: app
        image: payment-service:node-latest  # Safe Node.js version

---
## Keep non-critical services on Bun for testing
apiVersion: apps/v1
kind: Deployment
metadata:
  name: analytics-service
spec:
  template:
    spec:
      containers:
      - name: app
        image: analytics-service:bun-latest  # Keep testing Bun

Live Debugging Production Issues

🔥 Live Debugging Toolkit
Memory monitoring → Module patching → Signal handling fixes while in production

When you can't rollback and need to fix Bun issues while everything's on fire and Slack is exploding with angry messages.

Live debugging techniques: Bun debugger integration works with Chrome DevTools. Production debugging strategies apply to Bun runtime debugging. Memory profiling in production requires heap snapshot analysis.

Memory Leak Live Debugging:

// Add this to running Bun process
import { heapStats } from 'bun:jsc';

// Emergency memory monitoring
global.debugMemory = () => {
  const stats = heapStats();
  console.log({
    heap_mb: Math.round(stats.heapSize / 1024 / 1024),
    object_count: stats.objectCount,
    rss_mb: Math.round(process.memoryUsage.rss() / 1024 / 1024)
  });

  // Force GC if available (sometimes works)
  if (global.gc) {
    global.gc();
    console.log('Forced GC');
  }
};

// Call every 30 seconds to monitor
setInterval(global.debugMemory, 30000);

Module Resolution Live Fix:

// Patch module resolution at runtime
const originalRequire = require;
require = function(id) {
  try {
    return originalRequire(id);
  } catch (error) {
    if (error.code === 'MODULE_NOT_FOUND') {
      // Try alternative resolution paths
      const alternatives = [
        id + '/index.js',
        id + '/lib/index.js',
        id + '/dist/index.js'
      ];

      for (const alt of alternatives) {
        try {
          return originalRequire(alt);
        } catch (e) {
          continue;
        }
      }
    }
    throw error;
  }
};

Container Signal Handling Emergency Fix:

// Add proper signal handling to running process
process.on('SIGTERM', () => {
  console.log('SIGTERM received, shutting down gracefully');

  // Close database connections
  if (global.database) {
    global.database.close();
  }

  // Close HTTP server
  if (global.server) {
    global.server.close(() => {
      process.exit(0);
    });
  } else {
    process.exit(0);
  }
});

process.on('SIGINT', () => {
  console.log('SIGINT received, shutting down gracefully');
  process.exit(0);
});

Health Check Recovery

💓 Health Check Patterns
Bun response timing differs from Node → adjust timeouts and response handling

When load balancers are failing health checks due to Bun differences.

Health check strategies: Kubernetes health probes need runtime-specific configuration. Load balancer health checks require proper HTTP response timing. Application health patterns apply to Bun applications.

Emergency Health Check Endpoint:

// Health check that works with Bun quirks
app.get('/health', (req, res) => {
  const healthCheck = {
    status: 'ok',
    timestamp: Date.now(),
    uptime: process.uptime(),
    memory_mb: Math.round(process.memoryUsage.rss() / 1024 / 1024),
    runtime: 'bun',
    version: process.versions.bun
  };

  // Test database connectivity
  try {
    // Quick DB ping - adjust for your database
    db.query('SELECT 1');
    healthCheck.database = 'connected';
  } catch (error) {
    healthCheck.database = 'failed';
    healthCheck.status = 'unhealthy';
  }

  // Respond immediately - don't let timeouts happen
  res.writeHead(healthCheck.status === 'ok' ? 200 : 503, {
    'Content-Type': 'application/json',
    'Cache-Control': 'no-cache'
  });
  res.end(JSON.stringify(healthCheck));
});

Data Consistency Recovery

When Bun runtime differences cause data corruption or inconsistency.

Database Transaction Recovery:

// Check for partial transactions left by Bun crashes
async function recoverIncompleteTransactions() {
  // Find transactions that started but never completed
  const incomplete = await db.query(`
    SELECT transaction_id, started_at
    FROM transaction_log
    WHERE status = 'STARTED'
    AND started_at < NOW() - INTERVAL '5 minutes'
  `);

  for (const tx of incomplete) {
    console.log(`Rolling back incomplete transaction: ${tx.transaction_id}`);

    // Rollback incomplete transaction
    await db.query(`
      UPDATE transaction_log
      SET status = 'ROLLED_BACK', ended_at = NOW()
      WHERE transaction_id = $1
    `, [tx.transaction_id]);
  }
}

// Run during startup after Bun crash
await recoverIncompleteTransactions();

File System Consistency Check:

// Bun file operations might leave temp files or partial writes
import { readdir, stat, unlink } from 'fs/promises';

async function cleanupOrphanedFiles() {
  const tempDir = '/tmp/app-cache';
  const files = await readdir(tempDir);

  for (const file of files) {
    const filePath = `${tempDir}/${file}`;
    const stats = await stat(filePath);

    // Remove files older than 1 hour
    if (Date.now() - stats.mtime.getTime() > 3600000) {
      await unlink(filePath);
      console.log(`Cleaned up orphaned file: ${filePath}`);
    }
  }
}

Post-Incident Analysis

After recovery, analyze what went wrong to prevent repeat failures.

Collect Bun-Specific Logs:

## Gather comprehensive failure evidence
kubectl logs deployment/api-server --previous > bun-crash.log
docker exec container-name bun --print > bun-config.log

Performance Comparison Analysis:

// Add runtime telemetry for Bun vs Node comparison
const metrics = {
  startup_time: process.uptime(),
  memory_usage: process.memoryUsage(),
  runtime: process.versions.bun ? 'bun' : 'node',
  errors: [],
  performance_markers: []
};

// Send to monitoring system
await fetch('/api/telemetry', {
  method: 'POST',
  body: JSON.stringify(metrics)
});

Prevention Checklist:

• CPU architecture validated (AVX2 support)
• All native modules identified and replaced
• Docker signal handling fixed (--init flag)
• Memory monitoring implemented
• Rollback procedures tested
• Health checks adapted for Bun
• Team trained on Bun-specific debugging

Bun production failures are way messier than Node failures because the ecosystem is smaller and the docs suck ass. Always have a Node rollback plan ready because you'll definitely need it at 3am.