[Bug] Debugging issue for startup files

[P5175]

Bug Report

Description

Breakpoints in VS Code are always unbound (hollow circle) when trying to debug the Ever-Gauzy API on Windows + WSL2. The root cause is that the @nx/js:node executor attaches --inspect to the Nx wrapper process (node-with-require-overrides.js), not the actual API child process that runs the application code.

Environment

OS	Windows 10 + WSL2 (Ubuntu)
VS Code	Remote-WSL extension (opened via code . from WSL terminal)
Node	v24.14.0 via NVM
Package Manager	yarn
@nx/js version	22.5.2
RAM	16GB

Steps to Reproduce

1. Clone ever-gauzy on WSL2
2. Run yarn start:api
3. Open VS Code via code . from WSL terminal
4. Set a breakpoint in packages/core/src/lib/bootstrap/index.ts or apps/api/src/main.ts
5. Select "Debug Server" config from .vscode/launch.json and press F5

Expected Behavior

Breakpoint is hit and execution pauses at the breakpoint in the .ts source file.

Actual Behavior

Breakpoints show as unbound (hollow circle) with message:

"Some of your breakpoints could not be set"

The debugger attaches to the Nx wrapper process (node-with-require-overrides.js), not the actual API process. Verified via:

ps aux | grep inspect
# Shows --inspect-brk on node-with-require-overrides, NOT on the API

The Loaded Scripts panel in VS Code is empty — confirming the debugger is attached to the wrong process.

Root Cause Analysis

In node_modules/@nx/js/src/executors/node/node.impl.js:

// The --inspect flag is passed to the Nx wrapper via execArgv
task.childProcess = fork(join(__dirname, loaderFile), options.args ?? [], {
    execArgv: getExecArgv(options), // <-- inspect goes here (wrapper)
    ...
});

// But the actual app is launched inside via dynamicImport()
// which has NO inspector attached
dynamicImport(fileToRun); // <-- actual API code, no debugger

What I've Tried

• inspect-brk in apps/api/project.json — pauses at Nx internal file, not app code
• Various sourceMapPathOverrides in launch.json
• resolveSourceMapLocations config
• NODE_OPTIONS=--inspect
• Auto Attach (Smart mode) in VS Code
• Running node --inspect-brk dist/apps/api/main.js directly

Source Map Investigation

The source map in dist/apps/api/node_modules/@gauzy/core/src/lib/bootstrap/index.js.map uses relative paths:

../../../../../../packages/core/src/lib/bootstrap/index.ts

Which resolves to the wrong path:

/home/user/ever-gauzy/dist/apps/api/packages/core/... ❌

Instead of:

/home/user/ever-gauzy/packages/core/... ✅

Question

Is there an official supported way to debug the API on Windows + WSL2? The wiki mentions yarn start:api + "Debug Server" config but this was written in 2020 and no longer works with the current Nx executor architecture.

A working launch.json configuration for WSL2 would be very helpful for new contributors on Windows.

Related

• Fix: Debugger on API #1354
• https://github.com/ever-co/ever-gauzy/wiki/Debugging-Gauzy-Backend
• fix: #1354 debugger config for backend #1480