Out of Memory Exception - Java Heap


You see one of the following stacktraces on jenkins.log:

java.lang.OutOfMemoryError: Java heap space
java.lang.OutOfMemoryError: GC Overhead limit exceeded


  • Jenkins
  • CloudBees Jenkins Enterprise (CJE)
  • CloudBees Jenkins Team (CJT)
  • CloudBees Jenkins Platform (CJP)


1. Set right Heap Size

To set the heap size, you can update -Xms and -Xmx parameters in the command-line argument of the JVM.

Jenkins should not be started with less than -Xmx2g. However, for production environment with a considerable job workload, Jenkins should run with -Xmx16g or so. In the case your instance demands more than -Xmx16g any of the following points could be happening

  • Other factors, apart from the Heap Size, are not taking into consideration for improving your performance. please review: CJP Performance Best Practices for Linux
  • Your instance is not able to support its current workload (number of jobs and configuration) so you should consider about scaling horizontally your infra (more masters) to divide this workload more efficiently.

Best Practices

  1. Set your minimum heap size ( -Xms) to at least 1/2 of your maximum size ( -Xmx).
  2. For 64 bit JVM, set -Xmx less than 32G to benefit from -XX:+UseCompressedOops (which comes activated by default in recent JVM).
  3. Oracle recommends initially dedicating 50% of the available memory to the PGA (Server), and 50% to the SGA (System). Extending it to Jenkins running on Docker: Docker container should run with a heap memory no higher than 1/2 memory of the Host.
  4. The Jenkins Monitoring Plugin can be installed temporally (It’s not recommendable for Production Environments) to monitor the performance of your instance, the right heap value which should be a value between 80-90% of total heap consumption when the instance is at the maximum workload. Big heap memory values might produce big GC pauses which means slowness and sometimes even side effects like agent disconnections.

2. Tuning your Garbage Collector according to your Heap Size

Garbage collection (GC) is a dynamic approach to automatic memory management and heap allocation that processes and identifies dead memory blocks and reallocates storage for reuse.

As explained in Prepare Jenkins for Support > Java Parameters > Section II

3. Further diagnostics

If you continue to encounter issues even after the heap space increase and set correct GC settings, then we would need more diagnostic information to debug further. In order to investigate the cause of the Out of Memory Exception you will need to attach to the ticket:

Have more questions? Submit a request


Please sign in to leave a comment.