How to Fix Bun Runtime Errors and Compatibility Issues

In this tutorial, you'll learn about How to Fix Bun Runtime Errors and Compatibility Issues. We cover key concepts, practical examples, and best practices to help you understand and apply this topic effectively.

The Problem

Your Bun application crashes with TypeError: fetch failed or error: Cannot find module 'buffer' or segmentation faults (SIGSEGV). Bun aims for full Node.js compatibility but does not implement every Node.js API — especially some fs module Sync APIs, certain crypto features, and native C++ addons. Code written for Node.js may silently fail or crash when run with Bun.

Quick Fix

1. Use the --bun Polyfill flag

bun --bun run app.js

Expected output:

# Works if compatibility polyfills are sufficient

If it still fails, check the specific API by running:

bun --bun run -e "console.log(typeof require('fs').existsSync)"

If undefined, that API is not implemented.

2. Use Bun-native APIs for better performance

// ❌ Node.js fs (slower in Bun, some APIs missing)
import * as fs from 'node:fs';
const data = fs.readFileSync('file.txt', 'utf-8');

// ✅ Bun native (faster, full API)
const data = await Bun.file('file.txt').text();
console.log(data);

// ✅ Bun file writing
await Bun.write('output.txt', 'Hello Bun!');

// ✅ Bun environment variables
const dbUrl = Bun.env.DATABASE_URL;

3. Replace native C++ addons with pure-JS alternatives

# Replace bcrypt with bcryptjs
bun remove bcrypt
bun add bcryptjs

// Instead of:
// import bcrypt from 'bcrypt';
// const hash = await bcrypt.hash('password', 10);

// Use:
import bcrypt from 'bcryptjs';
const hash = await bcrypt.hash('password', 10);
console.log('Hash:', hash);

Expected output:

Hash: $2a$10$...

4. Use process.env and Bun.env interchangeably

// Both work in Bun:
const port1 = process.env.PORT || 3000;
const port2 = Bun.env.PORT || 3000;

console.log({ port1, port2 });

Bun.env is faster but only available in Bun.

5. Run with verbose error output

bun run --throw src/index.ts 2>&1

Expected output (error):

123 | crypto.createHash('md5')
     ^
error: crypto.createHash is not a function. (It may need a polyfill.)

6. Check and upgrade Bun

bun --version
bun upgrade

Expected output:

1.0.25
Already on the latest version

7. Test with Bun's built-in test runner

bun test

Expected output:

bun test v1.0.25
  ✓ src/__tests__/app.test.ts > handles errors correctly
  ✓ src/__tests__/app.test.ts > returns valid response
  2 pass
  0 fail
  Ran 2 tests across 1 files. [100.00ms]

8. Run TypeScript directly without Transpilation

Bun natively runs TypeScript without configuration:

bun run server.ts

9. Use Bun's built-in SQLite driver for database operations

import { Database } from 'bun:sqlite';
const db = new Database('app.db');
db.run('CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)');

This avoids compatibility issues with Node.js SQLite packages.

Prevention

• Use bun run --bun to enable Node.js compatibility polyfills by default
• Prefer Bun-native APIs (Bun.file, Bun.write, Bun.env) over Node.js equivalents where possible
• Avoid native C++ addons — choose pure-JS alternatives (bcryptjs, jsonwebtoken, etc.)
• Test with bun test which is Bun's built-in fast test runner that supports Jest-compatible APIs
• Check the Bun compatibility table before migrating a Node.js project to Bun