bun:debug

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: