Diagnose and Fix NetBeans Indexing Hangs and High CPU During Project Sync

When Indexing Stalls and CPU Spikes

In a large Java project, the NetBeans status bar may show Indexing… for minutes while CPU usage sits near 100% and the IDE feels frozen. The cause is usually not a NetBeans bug but a combination of project layout, JVM heap limits, a corrupt cache, or external build tools writing files at the same time. This guide walks through a diagnostic sequence: recognize the condition, check likely causes in order, apply the fix that matches your finding, and know when to escalate.

Recognizable Condition

• The bottom-right status bar shows a spinning Indexing… indicator that never clears.
• CPU usage stays high (80–100%) while the IDE appears idle.
• Code completion, navigation, and builds are delayed or time out.
• The IDE log (Help > View IDE Log) shows repeated indexing warnings or OutOfMemoryError entries.

Cause and Diagnostic Table

Possible Cause	How to Check	Typical Fix
Build output directories (target/, build/) or .git/ being scanned	Check project excludes; watch which paths appear in the indexing progress detail	Exclude build and VCS directories from scanning
Insufficient JVM heap (default -Xmx too low)	Inspect netbeans.conf; monitor heap and GC with VisualVM or JConsole	Raise -J-Xmx in netbeans.conf
Corrupt user-directory cache	Log shows cache read errors; problems survive restarts but not a fresh user dir	Delete the cache folder and let NetBeans rebuild it
File system watcher overwhelmed by many small files	Project root contains thousands of generated files (logs, temp files, node_modules)	Move generated files out of the project tree or exclude them
Maven/Gradle writing files while NetBeans indexes	An external build runs concurrently with the stall	Avoid simultaneous builds; re-index after builds finish

Ordered Diagnostic Checks

1. Confirm the stall. Watch the status bar progress bar: is it advancing slowly or truly stuck? Open Help > View IDE Log and look for repeated indexing or memory errors.
2. Check the heap. Find netbeans.conf in the etc folder of your NetBeans installation (on Linux also possibly /etc/netbeans.conf). Look at the netbeans_default_options line for -J-Xmx. Alternatively, attach VisualVM (bundled with the JDK) to the running IDE and watch heap usage and GC activity during indexing. Sawtooth GC spikes with the heap pinned near the maximum indicate memory pressure.
3. Check what is being scanned. If the progress detail shows paths under target/, build/, or .git/, those directories are being indexed unnecessarily.
4. Rule out a corrupt cache. If the hang recurs at the same point after every restart, the cache is a prime suspect.
5. Check for concurrent builds. Verify no mvn or gradle process is writing to the project while NetBeans indexes.

Fixes Tied to Findings

Increase the JVM heap

Edit netbeans.conf (requires write permission on the install directory; use sudo on Linux if NetBeans is installed system-wide). Keep a backup copy first — a syntax error in this file can prevent the IDE from starting. Modify the netbeans_default_options value, for example:

netbeans_default_options="-J-client -J-Xss2m -J-Xms512m -J-Xmx2048m ..."

Restart NetBeans and re-check with VisualVM that the new maximum heap is in effect. Do not set -Xmx close to your physical RAM, or the OS will start swapping and performance will get worse, not better.

Exclude build and VCS directories

Right-click the project, open Properties, and under the Sources category add exclusion patterns such as target/** and build/** if they are missing. Maven and Gradle projects in NetBeans normally exclude these automatically; if yours does not, that itself is a clue the project was imported incorrectly. After changing exclusions, trigger a re-index and watch whether the stall clears.

Clear the cache

Close NetBeans, then locate the cache directory — typically ~/.cache/netbeans/<version> on Linux, ~/Library/Caches/NetBeans/<version> on macOS, and under %APPDATA%\NetBeans\<version>\var\cache on Windows (the exact path is shown in Help > About). Rename the folder rather than deleting it, restart the IDE, and let it re-index. Expect the first indexing pass after a cache clear to take a while; that is normal and temporary. If the problem disappears, delete the renamed backup.

Reduce file watcher load and build conflicts

Move generated artifacts (logs, temp files, dependency folders like node_modules) out of the project root, or exclude them. Avoid running external Maven or Gradle builds while NetBeans is indexing; if you must, wait for the build to finish and then let NetBeans re-sync rather than fighting over the same files.

Verifying the Fix

• The Indexing… indicator completes and disappears within a reasonable time for your project size.
• Idle CPU usage drops back to low single digits after indexing finishes.
• The IDE log shows no new OutOfMemoryError or repeated indexing warnings.
• Code completion and navigation respond immediately after the status bar clears.

Escalation Criteria

If the hang persists after all of the above:

• Test with a fresh user directory (start NetBeans with --userdir /tmp/nb-test) to isolate configuration corruption.
• Disable third-party plugins that hook into parsing or indexing.
• Reproduce with a minimal project to determine whether the issue is project-specific.
• If reproducible, file a bug with the Apache NetBeans project, attaching the IDE log and your exact version and JDK details. Behavior described here applies to recent Apache NetBeans releases; verify paths and option names against your installed version, since defaults change over time.

Limitations

• Raising the heap too far causes OS-level swapping on machines with limited RAM.
• Clearing the cache forces a full re-index of all open projects, which temporarily degrades performance.
• Manual edits to netbeans.conf can prevent startup; always keep a backup.