# How to Debug Deno Applications: Complete Guide to Inspector Flags and DevTools Integration

> Learn to debug Deno applications effectively using inspector flags like --inspect. Connect Chrome DevTools or VS Code for seamless development. Master Deno debugging today.

- Repository: [Deno/deno](https://github.com/denoland/deno)
- Tags: how-to-guide
- Published: 2026-02-26

---

**To debug Deno applications, start the runtime with the `--inspect`, `--inspect-brk`, or `--inspect-wait` CLI flags to expose a V8 inspector WebSocket endpoint, then attach Chrome DevTools, VS Code, or use programmatic APIs like `Deno.inspect` and the `node:inspector` module.**

The Deno runtime in the `denoland/deno` repository provides a comprehensive debugging stack built on the V8 inspector protocol. Understanding these debugging methods allows you to diagnose TypeScript and JavaScript issues efficiently, from simple logging to complex multi-worker debugging sessions.

## Using the Inspect CLI Flags

The primary entry points for debugging Deno applications are three flags defined in [`cli/args/flags.rs`](https://github.com/denoland/deno/blob/main/cli/args/flags.rs):

- **`--inspect`** – Starts the inspector server on the default port (9229) without breaking execution.
- **`--inspect-brk`** – Pauses execution at the first line of user code and waits for a debugger to attach.
- **`--inspect-wait`** – Blocks the runtime until a debugger connects, but does not set an initial breakpoint.

When these flags are present, [`runtime/worker.rs`](https://github.com/denoland/deno/blob/main/runtime/worker.rs) constructs a `JsRuntimeInspector` and creates a local session via `JsRuntimeInspector::create_local_session`, establishing the bridge between V8 and the external debugger.

```bash
deno run --inspect-brk --allow-net server.ts

```

## Connecting Chrome DevTools

Once the inspector server starts, it exposes a WebSocket endpoint (e.g., `ws://127.0.0.1:9229/<uuid>`) implemented in [`libs/inspector_server/lib.rs`](https://github.com/denoland/deno/blob/main/libs/inspector_server/lib.rs). The `InspectorServer` struct handles HTTP upgrades to WebSocket on the `/ws` path and forwards Chrome DevTools Protocol (CDP) messages to the V8 engine.

To connect:

1. Run your application with `--inspect-brk` or `--inspect`.
2. Open Chrome and navigate to `chrome://inspect`.
3. Click **Configure...** and add the printed WebSocket address if not auto-discovered.
4. Click **Inspect** to open DevTools with access to Sources, Console, and Network panels.

## Debugging with VS Code

For integrated IDE debugging, configure [`.vscode/launch.json`](https://github.com/denoland/deno/blob/main/.vscode/launch.json) to attach to the inspector endpoint:

```json
{
  "type": "pwa-node",
  "request": "launch",
  "name": "Debug Deno",
  "program": "${workspaceFolder}/main.ts",
  "runtimeExecutable": "deno",
  "runtimeArgs": [
    "run",
    "--inspect-brk",
    "--allow-all"
  ],
  "cwd": "${workspaceFolder}"
}

```

Press **F5** to launch. VS Code connects to the same WebSocket endpoint as Chrome DevTools, providing breakpoints, variable inspection, and the Debug Console for evaluating expressions.

## Programmatic Object Inspection with Deno.inspect

For runtime debugging without an external debugger, `Deno.inspect` provides formatted object serialization useful for logging and REPL sessions:

```typescript
const data = { nested: { array: [1, 2, 3] } };
console.log(Deno.inspect(data, { depth: 2, colors: true }));

```

You can customize output by implementing `[Symbol.for("Deno.customInspect")]`:

```typescript
class SecureData {
  #secret: string;
  constructor(secret: string) {
    this.#secret = secret;
  }
  
  [Symbol.for("Deno.customInspect")]() {
    return "[SecureData: hidden]";
  }
}

console.log(Deno.inspect(new SecureData("password"))); 
// Output: [SecureData: hidden]

```

## Using the Node.js Compatible Inspector Module

Deno provides a Node.js-compatible `inspector` module for scripts requiring the Node API, implemented in [`ext/node/ops/inspector.rs`](https://github.com/denoland/deno/blob/main/ext/node/ops/inspector.rs):

```typescript
import { open, close } from "node:inspector";

open(); // Starts inspector server programmatically on an available port
console.log("Debugger attached...");
setTimeout(() => close(), 10000);

```

The `inspector.open()` and `inspector.close()` operations bridge to Deno's internal `InspectorServer`, respecting the same CLI flags while providing the familiar Node.js interface.

## Advanced Debugging Features

**Worker Debugging**: Web Workers forward their inspector sessions through `MainInspectorSessionChannel` (defined in [`runtime/web_worker.rs`](https://github.com/denoland/deno/blob/main/runtime/web_worker.rs)), allowing you to debug isolated workers within the same Chrome DevTools or VS Code window.

**Multiple Concurrent Sessions**: The global `Arc<InspectorServer>` (referenced as `GLOBAL_INSPECTOR_SERVER` in [`libs/inspector_server/lib.rs`](https://github.com/denoland/deno/blob/main/libs/inspector_server/lib.rs)) supports multiple simultaneous debugging connections.

**Live Share Support**: Use `--inspect-publish-uid <uid>` to publish unique identifiers for VS Code Live Share debugging sessions, enabling collaborative debugging across different machines.

## Summary

- **Start debugging** with `--inspect` (non-blocking), `--inspect-brk` (break on start), or `--inspect-wait` (wait for connection).
- **Connect clients** via Chrome DevTools at `chrome://inspect` or VS Code launch configurations targeting the WebSocket endpoint.
- **Inspect objects** using `Deno.inspect` with options for depth and colors, or implement `[Symbol.for("Deno.customInspect")]` for custom representations.
- **Use Node compatibility** through the `node:inspector` module for existing Node.js debugging scripts.
- **Debug workers** through the same inspector interface via `MainInspectorSessionChannel`.

## Frequently Asked Questions

### What is the difference between --inspect-brk and --inspect-wait?

`--inspect-brk` pauses execution at the first line of user code and waits for a debugger to attach, allowing you to step through initialization logic. `--inspect-wait` blocks the runtime until a debugger connects but does not set an initial breakpoint, letting the code run immediately upon attachment.

### Can I debug Deno Workers using the same inspector session?

Yes. Workers forward their inspector sessions through `MainInspectorSessionChannel` as implemented in [`runtime/web_worker.rs`](https://github.com/denoland/deno/blob/main/runtime/web_worker.rs), allowing you to debug multiple workers within the same Chrome DevTools or VS Code session without starting separate inspector instances.

### How do I hide sensitive data in console output when debugging?

Implement `[Symbol.for("Deno.customInspect")]` on your class to return a sanitized string representation. This method is automatically called by `Deno.inspect` and the console when formatting objects for display.

### Where is the inspector server implementation located in the Deno source code?

The WebSocket inspector server is implemented in [`libs/inspector_server/lib.rs`](https://github.com/denoland/deno/blob/main/libs/inspector_server/lib.rs) (containing the `InspectorServer` struct), while the runtime integration creating `JsRuntimeInspector` occurs in [`runtime/worker.rs`](https://github.com/denoland/deno/blob/main/runtime/worker.rs). CLI flag parsing happens in [`cli/args/flags.rs`](https://github.com/denoland/deno/blob/main/cli/args/flags.rs), and Node.js compatibility operations are in [`ext/node/ops/inspector.rs`](https://github.com/denoland/deno/blob/main/ext/node/ops/inspector.rs).