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

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:

• --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 constructs a JsRuntimeInspector and creates a local session via JsRuntimeInspector::create_local_session, establishing the bridge between V8 and the external debugger.

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. 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 to attach to the inspector endpoint:

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

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")]:

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:

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), 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) 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, 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 (containing the InspectorServer struct), while the runtime integration creating JsRuntimeInspector occurs in runtime/worker.rs. CLI flag parsing happens in cli/args/flags.rs, and Node.js compatibility operations are in ext/node/ops/inspector.rs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}