Skip to main content
When your local Jenkins instance throws an out-of-memory error loading the dashboard on localhost:8080, you may see an HTTP 500 response indicating that the Java heap space has been exhausted:
The image shows an HTTP 500 error page indicating a "jakarta.servlet.ServletException: Unexpected Exception" caused by a "java.lang.OutOfMemoryError: Java heap space" during a login attempt.
You can quickly confirm this by inspecting the Jenkins logs: 
journalctl -u jenkins | grep -i OutOfMemoryError
Example output: 
Feb 05 16:11:33 SilentShadow jenkins[158]: Exception: java.lang.OutOfMemoryError thrown from the UncaughtExceptionHandler in thread "EventHistoryStore.autoExpireTimer"
Feb 05 16:11:42 SilentShadow jenkins[158]: java.lang.OutOfMemoryError: Java heap space
Feb 05 16:42:59 SilentShadow jenkins[158]: java.lang.OutOfMemoryError: Java heap space

​
1. Checking Current JVM Heap Settings

Jenkins runs as a systemd service. To view the JVM options set for Jenkins, run: 
systemctl cat jenkins
Near the bottom of the output, locate the Environment="JAVA_OPTS=..." line showing -Xms and -Xmx values. For example, your service may currently be limited to 90 MB:
The image shows a Visual Studio Code window with a terminal open, displaying a configuration file related to Jenkins service settings. The text includes comments and settings for file descriptor limits, process limits, and umask values.
CloudBees recommends different heap configurations depending on your environment:
Platform TypeInitial Heap (-Xms)Maximum Heap (-Xmx)
Traditional (VM/Bare Metal)4 GBUp to 16 GB (scale horizontally if > 16 GB)
ContainerizedUse container memory flags or percentage-based settingsUse container memory flags or percentage-based settings
For Kubernetes or Docker deployments, leverage -XX:MaxRAMPercentage or orchestrator memory limits rather than hard-coded values.
The image shows a webpage from CloudBees documentation discussing best practices for Java heap memory settings on traditional and modern platforms, including the use of specific JVM arguments.
The image shows a webpage from CloudBees documentation, detailing recommended JVM specifications for CloudBees CI, including heap size and garbage collection settings.

​
3. Creating a Systemd Drop-in to Adjust Heap

To override the default JVM options without editing the main service file, create a systemd drop-in: 
sudo systemctl edit jenkins
Populate the editor with: 
[Service]
Environment="JAVA_OPTS=-Xms4G -Xmx4G"
Save and exit. This generates /etc/systemd/system/jenkins.service.d/override.conf.

​
4. Verifying the Changes

Before restarting, confirm your current Jenkins process: 
ps aux | grep -i jenkins
You might see something like: 
jenkins   158 15.4  4.1 10129960 666824 Ssl  15:48  18:53 /usr/bin/java -Xms90M -Xmx90M -jar /usr/share/java/jenkins.war --httpPort=8080
Now restart Jenkins and verify the new heap settings: 
sudo systemctl restart jenkins
ps aux | grep -i jenkins
Expected output: 
jenkins   27173 296  7.5 10877652 1234784 Ssl  —  /usr/bin/java -Xms4G -Xmx4G -jar /usr/share/java/jenkins.war --httpPort=8080

​
5. Confirm in the Jenkins UI

Refresh your Jenkins dashboard. The login page should load successfully, confirming that the JVM heap has been increased.
Regularly monitor heap usage, thread counts, and disk I/O as your Jenkins workloads grow. Insufficient headroom can lead to performance degradation or service outages.

​
References

Watch Video