IntelliJ IDEA breakpoints are ignored in a NestJS app
Breakpoints stay grey and are never hitShort answer
IntelliJ can only debug a NestJS app when the Node.js process runs with the inspector on and the IDE attaches to its port. Start the app with nest start --debug, check the debugger listens on 9229, attach with an Attach to Node.js/Chrome configuration, and make sure the Node.js plugins exist, which needs IntelliJ IDEA Ultimate.
Fix it fast
1Find out which cause you have
Start the app in debug mode from a terminal and read the first lines. Node.js prints the inspector address when the debugger is on. If you see no such line, the inspector never started.
npx nest start --debug --watch2Match what you see, then jump to its fix
- 1
No 'Debugger listening' line in the terminal; nothing listens on port 9229The app was started without the inspectorFix - 2
There is no Node.js or Attach to Node.js/Chrome entry under Run | Edit ConfigurationsIntelliJ has no Node.js debugging support in this edition or setupFix - 3
IntelliJ says it cannot connect, or the session closes at onceThe attach configuration uses the wrong host or portFix - 4
Debugging works once, then stops after you save a fileWatch mode restarts the process and drops the sessionFix
- 1
What does the error look like?
Breakpoints stay grey and are never hitNo 'Debugger listening' line appears when the NestJS app startsDebug session ends as soon as the NestJS app restarts
Cause 1 of 4
The app was started without the inspector
1Check
Check whether anything listens on the default inspector port.
lsof -i :92292Fix
Start Nest with --debug, which runs the app with the inspector flag, or run node --inspect on the compiled entry file. --inspect-brk pauses before your code starts, useful for startup bugs.
npx nest start --debug
# or, on the built output
node --inspect dist/main.js3Verify
The terminal prints the listening address and lsof shows a node process on 9229.
lsof -i :9229Confirmed by nodejs.org
Cause 2 of 4
IntelliJ has no Node.js debugging support in this edition or setup
1Check
JetBrains lists these as prerequisites: the JavaScript and TypeScript plugin enabled, plus the Node.js and JavaScript Debugger plugins, available only in IntelliJ IDEA Ultimate. Open Settings and look under Plugins.
# IntelliJ IDEA > Settings > Plugins > Installed: Node.js, JavaScript Debugger2Fix
Use IntelliJ IDEA Ultimate and enable those plugins. Without them the IDE has no Node.js debugger to attach.
# Settings > Plugins: enable Node.js and JavaScript Debugger3Verify
Run | Edit Configurations now offers Attach to Node.js/Chrome.
# Run | Edit Configurations | + | Attach to Node.js/ChromeConfirmed by jetbrains.com
Cause 3 of 4
The attach configuration uses the wrong host or port
1Check
Node.js listens at 127.0.0.1:9229 by default. JetBrains also says the debugger port must differ from the port your app serves on.
lsof -i :9229
lsof -i :30002Fix
In the Attach to Node.js/Chrome configuration enter host 127.0.0.1 and the inspector port. To use another port, pass it to Nest.
npx nest start --debug 127.0.0.1:92303Verify
Press Debug on the configuration; the console shows the debugger is attached and breakpoints turn solid.
# Run | Debug 'Attach to NestJS'Confirmed by jetbrains.com
Cause 4 of 4
Watch mode restarts the process and drops the session
1Check
A restarting watcher kills the process the debugger was attached to. JetBrains documents the fix for nodemon and the same setting applies to any restart.
npx nest start --debug --watch2Fix
Open the Attach to Node.js/Chrome configuration and tick Reconnect automatically so IntelliJ reattaches after each restart.
# Attach configuration > Reconnect automatically3Verify
Save a file, wait for the restart and confirm breakpoints still stop execution.
# Debug tool window shows the session reconnectConfirmed by jetbrains.com
How do I stop it coming back?
- Add a debug script to package.json so everyone starts the app the same way.
- Never bind the inspector to 0.0.0.0 or a public IP; use an SSH tunnel for remote debugging.
- Keep the app port and the inspector port different.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
Related fixes
Back end
TypeScript cannot find module '@nestjs/core' or its type declarations
error TS2307: Cannot find module '@nestjs/common' or its corresponding type declarations.
TS2307 means TypeScript searched node_modules and found neither the package nor its types.
3 causes, each with a fixBack end
Node.js in Docker Compose cannot reach MySQL on 127.0.0.1:3306
Error: connect ECONNREFUSED 127.0.0.1:3306
Inside a container, 127.0.0.1 is that container, not MySQL.
3 causes, each with a fixBack end
NestJS GraphQL cannot work out the output type of a field or query
Cannot determine a GraphQL output type for the "<name>". Make sure your class is decorated with an appropriate decorator.
In code-first mode Nest reads TypeScript types through decorators, and arrays, promises and unions disappear at runtime.
2 causes, each with a fixBack end
The nest command is not found in the terminal
bash: nest: command not found
The shell cannot find a nest executable on its PATH.
3 causes, each with a fixBack end
NestJS watch mode does not restart after I save a file
Changes show on the host but not in the running container
Watch mode only sees files that exist inside the process that runs it.
3 causes, each with a fixBack end
NestJS app will not start: Cannot find module '/app/dist/main'
Cannot find module 'dist/main'
Node cannot find dist/main.js because the build did not put it there.
4 causes, each with a fix