Demo Initial Settings and JVM Tunning

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.

2. Recommended Heap Settings

CloudBees recommends different heap configurations depending on your environment:

Platform Type	Initial Heap (`-Xms`)	Maximum Heap (`-Xmx`)
Traditional (VM/Bare Metal)	4 GB	Up to 16 GB (scale horizontally if > 16 GB)
Containerized	Use container memory flags or percentage-based settings	Use container memory flags or percentage-based settings

Note

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.

Warning

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

Watch video content