# How to Debug Bun Applications with VS Code: Complete Configuration Guide

> Effortlessly debug Bun applications in VS Code. Install the official extension, configure launch.json, and start debugging with F5. Your complete guide to troubleshooting Bun.

- Repository: [Bun/bun](https://github.com/oven-sh/bun)
- Tags: how-to-guide
- Published: 2026-02-28

---

**Debug Bun applications in VS Code by installing the official `oven.bun-vscode` extension, configuring [`.vscode/launch.json`](https://github.com/oven-sh/bun/blob/main/.vscode/launch.json) with `"type": "bun"`, and pressing F5 to launch or attach to the Bun runtime.**

The **Bun VS Code extension** provides first-class debugging support for JavaScript and TypeScript projects running on the Bun runtime. According to the `oven-sh/bun` source code, the extension integrates directly with Bun's WebKit Inspector protocol to enable breakpoints, variable inspection, and live error reporting. This guide covers the complete setup process using the official configurations documented in [`packages/bun-vscode/README.md`](https://github.com/oven-sh/bun/blob/main/packages/bun-vscode/README.md).

## Installing the Bun VS Code Extension

Install the **Bun** extension (ID: `oven.bun-vscode`) from the VS Code Marketplace. The extension automatically registers the Bun language server and debugger adapter, enabling debug support for `.js`, `.ts`, and `.tsx` files without additional tooling.

## Configuring launch.json for Bun Debugging

Create a [`.vscode/launch.json`](https://github.com/oven-sh/bun/blob/main/.vscode/launch.json) file in your project root to define debug profiles. The extension supports two primary **request** types: `"launch"` to start a new Bun process, and `"attach"` to connect to an already running process.

### Launch Configuration (New Process)

Use `"request": "launch"` to start your application under the debugger. The `"type": "bun"` field tells VS Code to use the Bun debug adapter.

```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "bun",
      "request": "launch",
      "name": "Debug Bun (watch)",
      "program": "${file}",
      "args": [],
      "cwd": "${workspaceFolder}",
      "env": {},
      "strictEnv": false,
      "watchMode": true,
      "stopOnEntry": false,
      "noDebug": false,
      "runtime": "bun",
      "runtimeArgs": []
    }
  ]
}

```

Key fields include:
- **`watchMode`**: Set to `true` for `--watch` or `"hot"` for `--hot` hot-reloading
- **`runtimeArgs`**: Passes arguments directly to the Bun executable (e.g., `--inspect`)
- **`stopOnEntry`**: Pauses execution on the first line when set to `true`

### Attach Configuration (Running Process)

Use `"request": "attach"` to debug a Bun process started with the inspector flag.

```bash
bun --inspect src/index.ts

# Output: ws://127.0.0.1:6499/

```

Then configure the attach profile:

```json
{
  "type": "bun",
  "request": "attach",
  "name": "Attach to Bun (inspect)",
  "url": "ws://127.0.0.1:6499/",
  "localRoot": "${workspaceFolder}",
  "remoteRoot": "/app"
}

```

The **`url`** field must match the WebSocket endpoint printed by `bun --inspect` or `bun --inspect-brk`.

## Enabling the Debug Terminal and Global Settings

Add Bun to the built-in JavaScript Debug Terminal and configure global behavior in [`.vscode/settings.json`](https://github.com/oven-sh/bun/blob/main/.vscode/settings.json):

```json
{
  "bun.runtime": "/usr/local/bin/bun",
  "bun.debugTerminal.enabled": true,
  "bun.debugTerminal.stopOnEntry": false,
  "bun.test.filePattern": "**/*{.test.,.spec.,_test_,_spec_}{js,ts,tsx,jsx,mts,cts,cjs,mjs}",
  "bun.test.customScript": "bun test"
}

```

The **`bun.debugTerminal.enabled`** setting adds Bun support to VS Code's integrated debug terminal, allowing you to launch debug sessions from the command palette. The **`bun.test.filePattern`** setting configures the test runner integration for the extension's test explorer.

## Watch Mode and Hot Reloading Support

Combine debugging with Bun's native watch mode by setting **`watchMode: true`** in your launch configuration. This is equivalent to running `bun --watch` and automatically restarts the debugger when files change.

For hot module reloading (preserving state where possible), set **`watchMode: "hot"`** to invoke `bun --hot`. Pair this with **`stopOnEntry: false`** to maintain a continuous debug session across reloads without breaking on startup.

## Inline Error Reporting

When a runtime error occurs, Bun sends the exact source location to the VS Code extension via the inspector protocol documented in [`packages/bun-inspector-protocol/README.md`](https://github.com/oven-sh/bun/blob/main/packages/bun-inspector-protocol/README.md). The extension displays inline diagnostics—red squiggly lines at the error location with hover tooltips containing stack traces—without requiring additional configuration.

For advanced debugging of Bun itself (native C++ internals), the repository provides LLDB pretty-printers in [`misctools/lldb/README.md`](https://github.com/oven-sh/bun/blob/main/misctools/lldb/README.md) and debug build instructions in [`CONTRIBUTING.md`](https://github.com/oven-sh/bun/blob/main/CONTRIBUTING.md).

## Summary

- Install the **`oven.bun-vscode`** extension from the VS Code Marketplace to enable Bun debugging
- Configure **`"type": "bun"`** in [`.vscode/launch.json`](https://github.com/oven-sh/bun/blob/main/.vscode/launch.json) with either `"request": "launch"` or `"request": "attach"`
- Start attach debugging by running **`bun --inspect`** and connecting to the printed WebSocket URL
- Enable **`watchMode: true`** or **`"hot"`** in launch configurations for automatic reloading during debug sessions
- Use **`bun.debugTerminal.enabled`** in settings to add Bun to VS Code's built-in JavaScript Debug Terminal

## Frequently Asked Questions

### How do I install the Bun debugger for VS Code?

Install the official extension (ID: `oven.bun-vscode`) from the VS Code Marketplace. The extension is developed and maintained in the `oven-sh/bun` repository under `packages/bun-vscode/` and provides the debug adapter for Bun applications.

### What is the difference between launch and attach modes?

**Launch** starts a new Bun process under the debugger using the entry point specified in `program`, while **Attach** connects to an existing process that was started with `bun --inspect` or `bun --inspect-brk`. Use attach when you need to debug a process already running in a terminal or container.

### How do I enable hot reloading while debugging?

Set **`watchMode: true`** in your launch configuration for standard file watching (equivalent to `--watch`), or use **`watchMode: "hot"`** for hot reloading (equivalent to `--hot`). Combine with **`stopOnEntry: false`** to prevent the debugger from pausing on every reload.

### Can I debug Bun tests in VS Code?

Yes. Configure **`bun.test.filePattern`** in [`.vscode/settings.json`](https://github.com/oven-sh/bun/blob/main/.vscode/settings.json) to match your test files, and use **`bun.test.customScript`** to specify the test runner command. The extension integrates with VS Code's test explorer to run and debug individual tests with full breakpoint support.