Skip to main content
workerd provides several tools and techniques for debugging both the runtime itself and your Workers code.

​
Running workerd with verbose logging

Enable verbose output to see detailed logs: 
workerd serve config.capnp --verbose
With the experimental flag: 
workerd serve config.capnp --verbose --experimental
Use --verbose when troubleshooting to see both application errors (JavaScript exceptions) and internal errors (runtime issues).

​
Watch mode for development

Automatically reload when config or code changes: 
just run serve samples/helloworld/config.capnp
Or manually: 
bazel run //src/workerd/server:workerd -- serve config.capnp --watch --verbose --experimental

​
Debugging in Visual Studio Code

​
Prerequisites

1

Save workspace

Ensure you have saved a VSCode workspace for workerd:File → Save Workspace As…
2

Install extensions

Install recommended extensions:Use Extensions: Configure Recommended Extensions (Workspace Folder) from the command palette.

​
Debug configurations

workerd includes several debug configurations in .vscode/launch.json:
ConfigurationDescription
workerd (dbg)Debug workerd server with a config file
workerd with inspector enabled (dbg)Debug with V8 inspector enabled
workerd test case (dbg)Debug a C++ test binary
workerd wd-test case (dbg)Debug a .wd-test file

​
Debugging the server

1

Open Run and Debug

Open the Run and Debug view:
  • Linux/Windows: Shift+Ctrl+D
  • macOS: Shift+Cmd+D
2

Select configuration

Choose workerd (dbg) or workerd with inspector enabled (dbg) from the dropdown.
3

Launch debugger

Press F5 to launch with the debugger attached.You’ll be prompted for a config file. Default: samples/helloworld/config.capnp
4

Set breakpoints

Set breakpoints in C++ or JavaScript code as needed.

​
Debugging tests

​
Debug a C++ test

  1. Select workerd test case (dbg)
  2. Press F5
  3. Enter the test binary path (default: bazel-bin/src/workerd/jsg/jsg-test)

​
Debug a .wd-test

  1. Select workerd wd-test case (dbg)
  2. Press F5
  3. Enter the test file path (default: src/workerd/api/node/path-test.wd-test)

​
Using LLDB with WPT tests

Debug Web Platform Tests with LLDB: 
just lldb-wpt-test urlpattern
This builds the test and launches it in LLDB for debugging.

​
Using the V8 Inspector

When you run workerd with inspector enabled, you can connect Chrome DevTools:
1

Start with inspector

Launch workerd with inspector enabled (VSCode: workerd with inspector enabled (dbg)).
2

Connect DevTools

Open Chrome/Edge and navigate to:
chrome://inspect
Your workerd instance should appear under Remote Target.
3

Debug JavaScript

Click inspect to open DevTools. You can:
  • Set breakpoints in JavaScript
  • Inspect variables
  • Profile performance
  • View console logs

​
Clangd for code navigation

Set up clangd for better code completion and navigation:
1

Install dependencies

just prepare
This installs gen-compile-commands and other tools.
2

Generate compile commands

just compile-commands
This creates compile_commands.json for project-wide operations like “Find References”.
3

Regenerate periodically

Run just compile-commands when new files are added to the project.
The compile_flags.txt file provides basic compiler arguments. If it’s not working, check docs/vscode.md for troubleshooting steps.

​
Common debugging scenarios

​
Debugging a Worker script

Create a test config file:
config.capnp
using Workerd = import "/workerd/workerd.capnp";

const config :Workerd.Config = (
  services = [
    (name = "main", worker = .mainWorker),
  ],
  sockets = [
    ( name = "http",
      address = "*:8080",
      http = (),
      service = "main"
    ),
  ]
);

const mainWorker :Workerd.Worker = (
  serviceWorkerScript = embed "worker.js",
  compatibilityDate = "2024-01-01",
);
Run with verbose logging: 
workerd serve config.capnp --verbose

​
Debugging memory issues

Run tests with AddressSanitizer: 
just test-asan //src/workerd/api/tests:encoding-test@

​
Debugging compilation errors

Stream test output to see full error messages: 
just stream-test //src/workerd/api/tests:encoding-test@

​
Finding the source of a crash

Use the debug build with symbols: 
bazel build //src/workerd/server:workerd
Then run under a debugger (GDB, LLDB, or VSCode).

​
Debugging tips

When debugging TypeScript workers, ensure your build process generates source maps. workerd will use them for better stack traces.
Many issues are resolved by using the correct compatibility date. See the compatibility dates documentation for details.
The samples/ directory contains working examples you can use as debugging references:
ls samples/
Use just stream-test instead of just test to see real-time output, which is helpful for debugging test failures.

​
Development container

workerd includes a devcontainer setup for consistent development environments:
  1. Install the Dev Containers extension
  2. Use Dev Containers: Open Folder In Container in VSCode
  3. The container includes all dependencies pre-configured
The devcontainer bootstrap may take time initially, but subsequent launches are cached.

​
Next steps

Testing

Learn to write and run tests

Wrangler integration

Use workerd with Wrangler

Build docs developers (and LLMs) love

Get started for freeTalk to us