NetBeans Debugger Breakpoints Not Hitting: Diagnostic Guide for Java SE Projects

Recognizable condition

When you start a debugging session in NetBeans, the debugger attaches to the JVM but the program runs to completion without stopping at any breakpoint. Breakpoints appear as normal icons (no red "X") but are ignored.

Cause / Diagnostic table

Possible cause	What to look for
Project JDK differs from IDE JDK	Project Properties → Sources → Java Platform shows a version not matching Help → About → IDE JDK.
Debug information omitted (-g missing)	Compiled .class files lack line‑number tables; javap -l shows no LineNumberTable.
Compile on Save disabled	Project Properties → Build → Compiling → "Compile on Save" unchecked; IDE may be debugging stale classes.
Debugger attached to wrong VM	Debugger Console shows connection to a different process ID or a remote host.

Ordered checks

1. Verify project JDK
   1. Open the project, right‑click → Properties → Sources → Java Platform.
   2. Note the JDK path (e.g., /usr/lib/jvm/java-11-openjdk).
   3. Open Help → About and check the IDE’s bundled JDK version.
   4. If they differ, proceed to the fix in step 3.

   Where to run: Inside NetBeans GUI; no special permissions needed.

   Expected check: Both JDK versions match (same major/minor).

   Risk: None.

2. Confirm debug information is present
   1. Open a terminal.
   2. Navigate to the project’s build/classes directory.
   3. Run javap -l fully‑qualified‑classname | grep LineNumberTable.
   4. If no output, the class was compiled without -g.

   Permissions: Read access to the class files.

   Expected check: At least one line‑number entry appears.

   Risk: None.

3. Ensure Compile on Save is enabled
   1. Project → Properties → Build → Compiling.
   2. Check the box "Compile on Save".
   3. If unchecked, enable it and click OK.

   Where: NetBeans IDE.

   Permissions: None.

   Expected check: The option stays checked after applying.

   Risk: None.

4. Verify debugger connection
   1. Start debugging (Debug → Debug Project).
   2. Open Window → IDE Tools → Debugger → Console.
   3. Look for a line like "Connected to process 12345" and ensure the PID matches the Java process you expect (you can check with jps -l in a terminal).
   4. If the PID differs or shows a remote host, the debugger is attached to the wrong VM.

   Where: Terminal for jps, NetBeans Debugger Console for connection info.

   Permissions: Ability to list Java processes (usually none).

   Expected check: PID from Debugger Console equals a PID from jps -l for your project’s main class.

   Risk: None.

Fixes tied to findings

Align project JDK with IDE JDK

1. Close NetBeans.
2. Edit the project’s nbproject/project.properties file (or use the GUI).
3. Change the javac.platform property to point to the IDE’s JDK (e.g., javac.platform=jdk11).
4. Save and reopen the project.
5. Clean and build: Run → Clean and Build Project.

Rollback: If the change causes compilation errors, restore the original project.properties from a backup or revert via Version Control.

Recompile with debug information

1. Project → Properties → Build → Compiling.
2. In the "Additional Compiler Options" field, add -g (if not already present).
3. Click OK.
4. Clean and build the project.

Rollback: Remove the -g flag and repeat the clean/build.

Enable Compile on Save (if disabled)

Follow the steps in the ordered checks section; no further action needed.

Reattach debugger to correct VM

1. Terminate any stray Java processes: pkill -f "your.main.Class" (use with caution).
2. Restart the debugging session.
3. Verify the PID in the Debugger Console matches the newly launched process.

Rollback: If you killed a needed process, restart it manually or re‑run the application from your IDE.

Escalation criteria

If after performing the JDK alignment, ensuring -g is present, enabling Compile on Save, and confirming the debugger attaches to the correct VM the breakpoints are still ignored:

1. Enable NetBeans debugger logging:
• Window → IDE Tools → Debugger → Console.
• Click the gear icon and select "Enable Logging".
• Reproduce the issue and examine the log for messages such as "Failed to set breakpoint at …" or "No line number information".
2. Check the NetBeans version‑specific bug database (e.g., Apache NetBeans JIRA) for known debugger issues with your JDK version.
3. Consider using a JDK version explicitly listed as supported in the NetBeans release notes (e.g., NetBeans 12.6 supports JDK 8‑11; JDK 17 may require a newer IDE build).

Practical verification: Create a minimal HelloWorld project, set a breakpoint on System.out.println("Hello");, run the debugger, and confirm it stops. If the HelloWorld works but your larger project does not, the problem is likely project‑specific (classpath, annotation processing, etc.).