Debugging non-primary worker in local wrangler-based environment with NodeJS inspector

[shvlv]

We have an application with several workers. The primary worker receives HTTP requests and puts data into the queue. The secondary worker consumes messages from the queue and performs the actual job.

If we run all workers with the single wrangler dev command with multiple config flags, everything works as expected, but the Node debugger can listen only to the primary worker. And it makes debugging almost useless because the internal worker does the actual work.

It's possible to run workers separately. Binging services are connected, but it looks like the queue is not. Messages are not consumed.

I found the https://developers.cloudflare.com/workers/vite-plugin/reference/debugging/ documentation, but I didn't try it because we have a pure backend application, and Vite seems like overkill.

What is the way to debug secondary workers?

[MukundaKatta]

The vite-plugin docs aren't the only path — and for a pure backend setup they're usually more than you want. Two approaches that work today with wrangler dev:

1. Separate wrangler dev processes with explicit inspector ports

The multi-worker-single-command setup only exposes one inspector. When you split them (the "multiple dev commands" path you linked), each wrangler dev gets its own inspector — but you have to opt into the right port for each:

# terminal 1 — primary
wrangler dev --config ./primary/wrangler.toml \
  --port 8787 --inspector-port 9229

# terminal 2 — queue consumer
wrangler dev --config ./consumer/wrangler.toml \
  --port 8788 --inspector-port 9230

Then attach a Node debugger (VS Code, chrome://inspect, node --inspect-client) to localhost:9230. Each worker gets its own inspector session and its own breakpoints, including inside the queue queue(batch, env, ctx) handler.

2. Wire the queue binding so messages actually flow

The reason your consumer isn't receiving messages in the multi-process setup is almost certainly the queue binding — service bindings cross processes happily, but queues do not by default when run in separate wrangler dev instances. What you need:

Producer (primary/wrangler.toml)

[[queues.producers]]
binding = "MY_QUEUE"
queue   = "my-queue"

Consumer (consumer/wrangler.toml)

[[queues.consumers]]
queue = "my-queue"
# Important: with --local, wrangler uses a file-backed local queue impl;
# both processes must agree on the state directory to see the same queue.
max_batch_size    = 10
max_batch_timeout = 1

Then run both with an explicitly shared persistence directory:

wrangler dev --config ./primary/wrangler.toml   --persist-to ./.wrangler/state --inspector-port 9229
wrangler dev --config ./consumer/wrangler.toml  --persist-to ./.wrangler/state --inspector-port 9230

The --persist-to flag pointed at the same path is the piece usually missing. Without it each wrangler dev gets its own Miniflare state directory and their queues are just two empty, disconnected files.

3. If you want one process but two inspectors

There's an open request upstream to expose per-worker inspectors in single-command multi-worker dev (workers-sdk#5961 is the most-relevant tracking issue last I checked). Until that lands, option 1 is the pragmatic route.

VS Code launch.json for two workers

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Attach: primary",
      "type": "node",
      "request": "attach",
      "port": 9229,
      "attachExistingChildren": false,
      "autoAttachChildProcesses": false
    },
    {
      "name": "Attach: consumer",
      "type": "node",
      "request": "attach",
      "port": 9230
    }
  ],
  "compounds": [
    { "name": "Attach both workers", "configurations": ["Attach: primary", "Attach: consumer"] }
  ]
}

Run "Attach both workers" and you can breakpoint across the queue boundary — publish in the primary, hit the consumer's breakpoint when the batch fires.

A non-obvious debugging tip: put a console.log('batch', batch.messages.length) at the very top of queue() before your breakpoints. If that log never fires, the problem is still the queue not being wired (see step 2); if it does fire but the debugger didn't stop, the problem is the inspector attachment (see step 1).

[tamish-max]

What has worked best for me in this situation is running the producer and consumer as separate wrangler dev processes, each with its own inspector port, but sharing the same persisted local state so the queue is visible to both processes.

For example:

# terminal 1: HTTP producer
wrangler dev --config ./primary/wrangler.toml \
  --port 8787 --inspector-port 9229 \
  --persist-to ./.wrangler/state

# terminal 2: queue consumer
wrangler dev --config ./consumer/wrangler.toml \
  --port 8788 --inspector-port 9230 \
  --persist-to ./.wrangler/state

And make sure the queue name matches on both sides:

[[queues.producers]]
queue = "jobs"
binding = "JOBS"

[[queues.consumers]]
queue = "jobs"
max_batch_size = 1

Two easy ways this breaks locally:

• each process gets a different persistence directory, so they don’t share queue state
• only one process defines the queue binding/name you expect

So yes: I think the path is “multiple wrangler dev commands”, but with shared --persist-to + separate --inspector-port values, not the single-command dev mode.