Debugger

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

Bun implements the WebKit Inspector Protocol, which lets you attach an interactive debugger to any running Bun process. You can debug using the hosted web inspector at debug.bun.sh or directly in VS Code.

Enabling the debugger

--inspect

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

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:

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:

bun --inspect-wait run server.ts

Setting a custom port or URL

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

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. 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.

1. Start your script with --inspect

   bun --inspect run server.ts
   
2. Open the debug URL in your browser

   Copy the https://debug.bun.sh/#... URL from the terminal and open it.

3. Set a breakpoint

   Navigate to the Sources tab. Click a line number to set a breakpoint.

4. Trigger the code path

   Send a request or run the code that hits the breakpoint. Execution pauses and the debugger activates.

5. Inspect and step

   Use the control buttons to continue, step over, step into, or step out of functions.

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.

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

{
  "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

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

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:

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, including Error.prepareStackTrace and Error.captureStackTrace:

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:

const fn = () => {
  function myInner() {
    throw err;
  }

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