debugging

14 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

--inspect flag for debugging

The --inspect flag starts your Deno program with an inspector server that allows connections from clients supporting the V8 Inspector Protocol, such as Chrome DevTools. You can visit chrome://inspect in a Chromium-based browser to connect and inspect code, add breakpoints, and step through execution. The default inspector server listens on 127.0.0.1:9229, but you can specify a custom port with --inspect=9230 or a custom host and port with --inspect=0.0.0.0:9229.

--inspect-wait flag for debugging

The --inspect-wait flag pauses program execution until a debugger client connects to the inspector server. This is useful for short programs where execution might finish before a debugger can connect.

--inspect-brk flag for debugging

The --inspect-brk flag waits for a debugger to connect and then places a breakpoint at the start of the program before execution begins. This is the most commonly used inspect flag. JetBrains and VSCode IDEs use this flag by default.

--inspect-publish-uid flag controls inspector URL output

The --inspect-publish-uid flag controls how the inspector WebSocket URL is published. With stderr (the default), the URL is printed to stderr on startup. With http, the URL is instead exposed via the /json/list HTTP endpoint on the inspector port, which is useful for programmatic tooling that polls for available targets.

Activate inspector at runtime with node:inspector module

You can activate the inspector on demand in a running program using the node:inspector module. The function inspector.open([port][, host][, wait]) starts the inspector server. The port defaults to 9229 and the host defaults to 127.0.0.1. The program needs the --allow-net permission (or -A) to bind a network socket. Related functions include: inspector.open(port, host, true) to block until a client connects (same as inspector.waitForDebugger()); inspector.url() to get the WebSocket URL or undefined if not active; and inspector.close() to stop the server.

SIGUSR1 signal activates inspector in running process

Starting with Deno 2.9.2, on Linux and macOS you can send the SIGUSR1 signal to a running Deno process to activate the inspector without restarting. The inspector server starts on the default 127.0.0.1:9229 without pausing execution and prints a banner to stderr. This requires no permissions and no cooperation from the program code. The signal has no effect if the inspector server is already running, and the signal handler is installed shortly after startup so it is intended for programs running longer than about half a second. SIGUSR1 does not exist on Windows.

Network traffic inspection in Chrome DevTools

Starting with Deno 2.8, Chrome DevTools can inspect network traffic made by Deno programs in the same way it inspects browser traffic. Run your program with --inspect-wait (or --inspect / --inspect-brk), open chrome://inspect in a Chromium-based browser, click Inspect on the Deno target, and switch to the Network tab. The Network tab shows requests from fetch(), node:http and node:https client requests, WebSocket client connections, and Deno.upgradeWebSocket() server-side upgrades. For each request you can see the URL, method, status code, request and response headers, request and response bodies, and timing information.

Web Workers debugging

Starting with Deno 2.7, Web Workers can be debugged through Chrome DevTools and VS Code. When you run your program with any --inspect flag, each spawned worker appears as a separate target in chrome://inspect alongside the main thread. Click Inspect on the worker target to open a dedicated DevTools panel for that worker where you can set breakpoints, step through code, and inspect variables independently of the main thread. In VS Code with the Deno extension, workers appear as separate threads in the Call Stack panel of the debugger.

--log-level=debug flag for inspector troubleshooting

If you have trouble connecting to the inspector, use the --log-level=debug flag to get more information about what is happening. This shows information like module resolution, network requests, and permission checks.

--strace-ops flag for profiling Deno ops

The --strace-ops flag prints out all ops being executed by Deno when a program runs, along with their timings. Deno ops are an RPC mechanism between JavaScript and Rust that provide functionality like file I/O, networking, and timers. Each op should have a Dispatch and a Complete event; the time between these is the execution time. This flag is useful for performance profiling, debugging hanging programs, or understanding how Deno works.

TLS session debugging with SSLKEYLOGFILE

Set the SSLKEYLOGFILE environment variable to log TLS session keys to a file. This enables you to decrypt and inspect encrypted network traffic with tools like Wireshark. Load the keys.log file in Wireshark (Edit > Preferences > Protocols > TLS > (Pre)-Master-Secret log filename) to decrypt captured TLS traffic.

OpenTelemetry integration for observability

Deno includes built-in support for OpenTelemetry for comprehensive observability and debugging in production applications. Set the OTEL_DENO environment variable to true and run your script to automatically collect and export runtime observability data including HTTP request traces, runtime metrics, console logs, and errors. This data can be exported to monitoring systems.

Inspector binding security caution

Binding the inspector to a public IP with an open port is insecure because it lets any host that can reach the port connect to the inspector and execute arbitrary code. Keep the host at 127.0.0.1 unless you fully control the network.

Inspector connection timing issue with --inspect

If you use the --inspect flag, the code starts executing immediately. If your program is short, you might not have enough time to connect the debugger before execution finishes. In such cases, try running with --inspect-wait or --inspect-brk instead, or add a timeout at the end of your code.

Give your agent this brain