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:
Example output:

​
1. Checking Current JVM Heap Settings

Jenkins runs as a systemd service. To view the JVM options set for Jenkins, run:
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:
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:
Populate the editor with:
Save and exit. This generates /etc/systemd/system/jenkins.service.d/override.conf.

​
4. Verifying the Changes

Before restarting, confirm your current Jenkins process:
You might see something like:
Now restart Jenkins and verify the new heap settings:
Expected output:

​
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