Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

IntelliJ IDEA breakpoints are ignored in a NestJS app

ErrorBreakpoints stay grey and are never hit

Short 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.

  • Applies to IntelliJ IDEA Ultimate, NestJS CLI, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 --watch
  2. 2Match what you see, then jump to its fix

    1. 1No 'Debugger listening' line in the terminal; nothing listens on port 9229The app was started without the inspectorFix
    2. 2There 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. 3IntelliJ says it cannot connect, or the session closes at onceThe attach configuration uses the wrong host or portFix
    4. 4Debugging works once, then stops after you save a fileWatch mode restarts the process and drops the sessionFix

What does the error look like?

  • Breakpoints stay grey and are never hit
  • No 'Debugger listening' line appears when the NestJS app starts
  • Debug 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 :9229

2Fix

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.js

3Verify

The terminal prints the listening address and lsof shows a node process on 9229.

lsof -i :9229

Confirmed by nodejs.org

Did this fix it?

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 Debugger

2Fix

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 Debugger

3Verify

Run | Edit Configurations now offers Attach to Node.js/Chrome.

# Run | Edit Configurations | + | Attach to Node.js/Chrome

Confirmed by jetbrains.com

Did this fix it?

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 :3000

2Fix

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:9230

3Verify

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

Did this fix it?

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 --watch

2Fix

Open the Attach to Node.js/Chrome configuration and tick Reconnect automatically so IntelliJ reattaches after each restart.

# Attach configuration > Reconnect automatically

3Verify

Save a file, wait for the restart and confirm breakpoints still stop execution.

# Debug tool window shows the session reconnect

Confirmed by jetbrains.com

Did this fix it?

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:

Related fixes

Back 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 fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.