Bun Debug Helper

Diagnose and resolve common issues in Bun applications.

Debugging Categories

Runtime Issues

Check for:

1. Module resolution - bun --print-resolved
2. Environment variables - Missing or incorrect env vars
3. Type errors - TypeScript configuration issues
4. Import errors - Incorrect import paths or missing exports

Commands:

# Check module resolution
bun --print-resolved src/index.ts

# Verbose output
bun --verbose run src/index.ts

# Check environment
bun --print env

Test Issues

Common problems:

1. Tests not found - Check file naming (*.test.ts)
2. Mock not working - Verify mock.module syntax
3. Timeout - Increase timeout in bunfig.toml
4. Coverage not generating - Add --coverage flag

Diagnostic commands:

# Run with verbose output
bun test --verbose

# Show test discovery
bun test --list

# Check timeout issues
bun test --timeout 30000

Build Issues

Check for:

1. Entry point - Verify entrypoints array
2. External packages - Check external configuration
3. Loaders - Ensure correct loader for file types
4. Output format - Verify target and format settings

Debug build:

const result = await Bun.build({
  entrypoints: ["./src/index.ts"],
  outdir: "./dist",
});

if (!result.success) {
  console.error("Build failed:");
  for (const log of result.logs) {
    console.error(log);
  }
}

Memory Issues

Commands:

# Run with memory stats
bun --smol run src/index.ts

# Check memory usage
bun --print-memory run src/index.ts

Common causes:

• Large file reads without streaming
• Unbounded caches
• Event listener leaks
• Large response bodies

Performance Issues

Profile with:

# CPU profile
bun --cpu-prof run src/index.ts

# Heap snapshot
bun --heap-prof run src/index.ts

Common causes:

• Synchronous file I/O
• Blocking operations
• Inefficient database queries
• Missing caching

Quick Diagnostics

Run these commands to gather information:

# Bun version
bun --version

# System info
bun --print-config

# Check dependencies
bun pm ls

# Verify lockfile
bun pm hash

# Check for outdated packages
bun outdated

Common Error Messages

Error	Cause	Solution
Cannot find module	Wrong import path	Check relative paths
SyntaxError	Invalid syntax	Check TypeScript config
ENOENT	File not found	Verify file exists
EADDRINUSE	Port in use	Kill process or change port
Segmentation fault	Native addon issue	Rebuild native modules

Debug Checklist

1. Check Bun version is latest
2. Verify bunfig.toml settings
3. Check package.json scripts
4. Validate TypeScript configuration
5. Test with minimal reproduction
6. Check for known issues on GitHub

Getting Help

If issue persists:

1. Create minimal reproduction
2. Check Bun GitHub issues
3. Check Bun Discord
4. Include Bun version and OS info

Output

After diagnosis:

1. Identified issue category
2. Specific problem found
3. Recommended fix
4. Commands to verify fix worked