Articles

Tune Jenkins JVM Heap Size to Prevent OutOfMemoryError (2026)

April 18, 2026 5 min read

Jenkins is running out of Java heap space, causing OutOfMemoryErrors and instability.

The fundamental issue is that the Java Virtual Machine (JVM) running Jenkins has a fixed amount of memory it can use for objects (the heap), and Jenkins, with its plugins and build history, is trying to use more than that limit.

Here’s how to diagnose and fix it, from most common to less common:

1. Insufficient Heap Size for Current Load

  • Diagnosis: Check the current JVM heap settings. These are typically configured in the jenkins.xml (Windows) or jenkins.sh (Linux) startup script, or in a dedicated jvmoptions file referenced by these scripts. Look for -Xms (initial heap size) and -Xmx (maximum heap size) flags.
    • Linux: grep 'Xmx' /etc/init.d/jenkins or grep 'Xmx' /usr/lib/jenkins/jenkins.sh (paths may vary).
    • Windows: Open C:\Program Files\Jenkins\jenkins.xml in a text editor and look for -Xmx.
  • Fix: Increase the -Xmx value. A common starting point for medium-sized Jenkins instances is 4096m (4GB). For larger instances, 8192m (8GB) or more might be necessary.
    • Example Linux: Edit /etc/init.d/jenkins and change -Xmx1024m to -Xmx4096m.
    • Example Windows: Edit jenkins.xml and change -Xmx2048m to -Xmx4096m.
  • Why it works: This directly tells the JVM to allocate more memory for its heap, allowing Jenkins to store more objects before running out.

2. Large Number of Concurrent Builds or Build Artifacts

  • Diagnosis: Monitor Jenkins’s "Build Executor Status" and "Build Queue" dashboards. If you consistently see many builds running concurrently, or a long build queue, Jenkins is under heavy load. Examine the size of build artifacts being stored or processed.
  • Fix: While increasing heap is the primary fix, consider optimizing your build pipelines.
    • Clean up workspaces: Add steps in your build jobs to clean up old build artifacts and workspace files. deleteDir(glob: '**/build/**') in a Jenkins pipeline.
    • Reduce artifact retention: Configure jobs to retain fewer build artifacts. In job configuration, under "Post-build Actions," reduce "Number of builds to keep."
    • Parallelization: Distribute builds across more Jenkins agents rather than overloading a single controller.
  • Why it works: Reducing the amount of data Jenkins needs to hold in memory (build artifacts, workspace data, etc.) or distributing the load means the JVM heap has less pressure.

3. Memory Leaks in Plugins

  • Diagnosis: If OutOfMemoryErrors started occurring after installing or updating a specific plugin, that plugin is a prime suspect. You can also use the "Thread Dump Analyzer" plugin (if Jenkins is still somewhat responsive) or external JVM profiling tools (like YourKit, JProfiler, or even jmap and jhat for advanced debugging) to identify which objects are consuming the most heap. Look for consistently growing object counts for specific plugin-related classes.
  • Fix:
    • Update/Disable Plugin: Update the suspect plugin to the latest version, which may contain a fix. If the problem persists, temporarily disable the plugin.
    • Report Bug: If it’s a confirmed leak, report it to the plugin’s maintainers.
  • Why it works: Plugins run within the Jenkins JVM. A poorly written plugin can fail to release memory it no longer needs, leading to a gradual increase in heap usage that eventually exhausts the available space.

4. Excessive Build History or Log Retention

  • Diagnosis: Check the "Configure System" -> "Global properties" -> "Project-based Matrix Authorization Strategy" (this is not the right place, it should be "Global Build History Size" or similar, let me correct that). Check "Configure System" -> "Global Build History Size" or job-specific settings for how many builds are kept. If this number is very high, Jenkins is storing a lot of metadata and logs in memory.
  • Fix: Reduce the number of builds to keep globally or per job.
    • Global: In Jenkins UI, go to "Manage Jenkins" -> "Configure System" -> "Global properties" (if you see it as a section, otherwise it’s often implicit in job retention defaults) or look for settings related to "Build History" or "Discard old builds" and set a reasonable limit (e.g., keep the last 10 builds).
    • Job-specific: In individual job configurations, under "Post-build Actions," check "Discard old builds" and set limits for "Max # of builds to keep."
  • Why it works: Each build record and its associated logs consume memory. Limiting the number of historical builds reduces the total amount of data Jenkins needs to manage in memory.

5. JVM Garbage Collection Tuning (Advanced)

  • Diagnosis: If you’re seeing frequent OutOfMemoryErrors despite adequate heap size and no obvious leaks, the JVM’s garbage collector might not be reclaiming memory efficiently enough. You can enable GC logging by adding -XX:+PrintGCDetails -XX:+PrintGCTimeStamps -Xloggc:/var/log/jenkins/gc.log (adjust path as needed) to your JVM options. Analyze the gc.log for long GC pauses or frequent full GCs.
  • Fix: Switch to a different garbage collector or tune the current one. For Jenkins, the G1GC (Garbage-First Garbage Collector) is often a good choice for large heaps. Add -XX:+UseG1GC to your JVM options. If G1GC is already in use, you might tune its parameters (e.g., -XX:MaxGCPauseMillis=200), but this is complex and highly system-dependent.
    • Example: Add -XX:+UseG1GC to your jenkins.xml or jvmoptions file.
  • Why it works: Different GC algorithms have different trade-offs. G1GC is designed to provide more predictable pause times for large heaps, which can help prevent the JVM from reaching an OutOfMemoryError state during long collection cycles.

6. Incorrectly Sized Heap for the Jenkins Controller

  • Diagnosis: If you’ve recently moved Jenkins to a new server or significantly changed its workload without adjusting the JVM heap, the current settings might be inappropriate. The system’s total RAM is also a factor; you shouldn’t set the heap to be larger than the available physical RAM minus OS and other process needs.
  • Fix: Re-evaluate the -Xmx value based on the server’s available RAM. A good rule of thumb is to leave at least 2-4GB for the OS and other processes, and allocate the rest to Jenkins. For a server with 16GB RAM, 8192m might be a good starting point for Jenkins.
  • Why it works: Ensures that Jenkins is configured to use a proportional amount of memory on its host system, preventing it from competing too aggressively with the operating system or other critical services.

After applying these fixes, restart Jenkins. The next error you might encounter is related to disk I/O bottlenecks if Jenkins is writing too much data too quickly, or potentially a java.lang.OutOfMemoryError: Metaspace if you’re running a very large number of classes (though this is less common than heap OOMs).

Want structured learning?

Take the full Jenkins course →