> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/oven-sh/bun/llms.txt
> Use this file to discover all available pages before exploring further.

# Debugger

> Debug Bun scripts interactively using the WebKit Inspector Protocol with Chrome DevTools or VS Code.

Bun implements the [WebKit Inspector Protocol](https://github.com/oven-sh/bun/blob/main/packages/bun-inspector-protocol/src/protocol/jsc/index.d.ts), which lets you attach an interactive debugger to any running Bun process. You can debug using the hosted web inspector at [debug.bun.sh](https://debug.bun.sh) or directly in VS Code.

## Enabling the debugger

### `--inspect`

Pass `--inspect` to start a WebSocket debug server alongside your script:

```bash theme={null}
bun --inspect run server.ts
```

Bun prints the connection URL:

```
------------------ Bun Inspector ------------------
Listening at:
  ws://localhost:6499/0tqxs9exrgrm

Inspect in browser:
  https://debug.bun.sh/#localhost:6499/0tqxs9exrgrm
------------------ Bun Inspector ------------------
```

### `--inspect-brk`

Identical to `--inspect`, but injects a breakpoint at the very first line of the script before any code executes. Useful for short-lived scripts that exit before you can attach a debugger:

```bash theme={null}
bun --inspect-brk run script.ts
```

### `--inspect-wait`

Identical to `--inspect`, but Bun waits for a debugger to attach before executing any code. Useful when you need to set breakpoints before the process starts:

```bash theme={null}
bun --inspect-wait run server.ts
```

### Setting a custom port or URL

All three flags accept an optional port number, hostname, or URL prefix:

```bash theme={null}
bun --inspect=4000 server.ts
bun --inspect=localhost:4000 server.ts
bun --inspect=localhost:4000/prefix server.ts
```

## Connecting a debugger

### `debug.bun.sh`

Bun hosts a web-based debugger at [debug.bun.sh](https://debug.bun.sh). It is a modified version of WebKit's Web Inspector, familiar to Safari users.

Open the URL printed by `--inspect` in your browser to start a session. The interface provides:

* **Sources tab** — View source code, set breakpoints, and step through execution.
* **Console tab** — Run arbitrary JavaScript in the context of your running program.
* **Scope inspector** — Examine local variables and their properties at any breakpoint.

<Steps>
  <Step title="Start your script with --inspect">
    ```bash theme={null}
    bun --inspect run server.ts
    ```
  </Step>

  <Step title="Open the debug URL in your browser">
    Copy the `https://debug.bun.sh/#...` URL from the terminal and open it.
  </Step>

  <Step title="Set a breakpoint">
    Navigate to the Sources tab. Click a line number to set a breakpoint.
  </Step>

  <Step title="Trigger the code path">
    Send a request or run the code that hits the breakpoint. Execution pauses and the debugger activates.
  </Step>

  <Step title="Inspect and step">
    Use the control buttons to continue, step over, step into, or step out of functions.
  </Step>
</Steps>

#### Execution controls

| Button                    | Description                                                        |
| ------------------------- | ------------------------------------------------------------------ |
| Continue script execution | Resume running until the next breakpoint or exception.             |
| Step over                 | Advance to the next line without entering function calls.          |
| Step into                 | Enter the function call on the current line.                       |
| Step out                  | Finish executing the current function and return to the call site. |

### VS Code debugger

Bun has experimental support for debugging in Visual Studio Code via the [Bun VS Code extension](https://marketplace.visualstudio.com/items?itemName=oven.bun-vscode).

After installing the extension, add a launch configuration to `.vscode/launch.json`:

```json theme={null}
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "bun",
      "request": "launch",
      "name": "Debug Bun script",
      "program": "${file}",
      "cwd": "${workspaceFolder}",
      "stopOnEntry": false,
      "watchMode": false
    },
    {
      "type": "bun",
      "request": "attach",
      "name": "Attach to Bun process",
      "url": "ws://localhost:6499/",
      "stopOnEntry": false
    }
  ]
}
```

Use the `"launch"` configuration to start and debug a script directly from VS Code, or use `"attach"` to connect to a process already running with `--inspect`.

## Debugging network requests

Set the `BUN_CONFIG_VERBOSE_FETCH` environment variable to log all `fetch()` and `node:http` requests automatically.

| Value   | Description                             |
| ------- | --------------------------------------- |
| `curl`  | Print each request as a `curl` command. |
| `true`  | Print request and response headers.     |
| `false` | No output. Default.                     |

### Log as `curl` commands

```typescript theme={null}
process.env.BUN_CONFIG_VERBOSE_FETCH = "curl";

await fetch("https://example.com", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ foo: "bar" }),
});
```

```
[fetch] $ curl --http1.1 "https://example.com/" -X POST -H "content-type: application/json" ...
[fetch] > HTTP/1.1 POST https://example.com/
[fetch] > content-type: application/json
...
[fetch] < 200 OK
[fetch] < Content-Type: text/html; charset=UTF-8
```

Lines prefixed with `>` are the outgoing request; lines with `<` are the response.

### Log request and response headers

```typescript theme={null}
process.env.BUN_CONFIG_VERBOSE_FETCH = "true";

await fetch("https://example.com", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ foo: "bar" }),
});
```

## Sourcemaps and stack traces

Bun transpiles every file it runs, but automatically generates sourcemaps so that stack traces point to your original TypeScript or JSX source — not the transpiled output. Sourcemaps are generated both for on-demand transpilation and for `bun build` output.

### Source preview on errors

When an unhandled exception occurs, Bun prints a syntax-highlighted source preview showing where the error originated:

```
1 | // Create an error
2 | const err = new Error("Something went wrong");
               ^
error: Something went wrong
      at file.js:2:13
```

You can generate this preview manually using `Bun.inspect`:

```typescript theme={null}
const err = new Error("Something went wrong");
console.log(Bun.inspect(err, { colors: true }));
```

### V8 stack trace compatibility

Bun uses JavaScriptCore, but formats `error.stack` to match Node.js's V8 output. This ensures compatibility with libraries that expect V8-style stack traces.

Bun also implements the [V8 Stack Trace API](https://v8.dev/docs/stack-trace-api), including `Error.prepareStackTrace` and `Error.captureStackTrace`:

```typescript theme={null}
Error.prepareStackTrace = (err, stack) => {
  return stack.map(callSite => callSite.getFileName());
};

const err = new Error("Something went wrong");
console.log(err.stack); // ["error.js"]
```

`Error.captureStackTrace` lets you adjust where a stack trace begins, which is useful in callback-heavy or async code:

```typescript theme={null}
const fn = () => {
  function myInner() {
    throw err;
  }

  try {
    myInner();
  } catch (err) {
    Error.captureStackTrace(err, fn);
    console.log(err.stack); // starts at the fn() call site
  }
};
```