> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Demo Initial Settings and JVM Tunning

> This article provides guidance on adjusting JVM heap settings for Jenkins to prevent out-of-memory errors.

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:

<Frame>
  ![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.](https://kodekloud.com/kk-media/image/upload/v1752870817/notes-assets/images/Certified-Jenkins-Engineer-Demo-Initial-Settings-and-JVM-Tunning/http-500-error-jakarta-servletexception.jpg)
</Frame>

You can quickly confirm this by inspecting the Jenkins logs:

```bash theme={null}
journalctl -u jenkins | grep -i OutOfMemoryError
```

Example output:

```bash theme={null}
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:

```bash theme={null}
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:

<Frame>
  ![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.](https://kodekloud.com/kk-media/image/upload/v1752870818/notes-assets/images/Certified-Jenkins-Engineer-Demo-Initial-Settings-and-JVM-Tunning/visual-studio-code-jenkins-config.jpg)
</Frame>

## 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 |

<Callout icon="lightbulb" color="#1CB2FE">
  For Kubernetes or Docker deployments, leverage `-XX:MaxRAMPercentage` or orchestrator memory limits rather than hard-coded values.
</Callout>

<Frame>
  ![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.](https://kodekloud.com/kk-media/image/upload/v1752870819/notes-assets/images/Certified-Jenkins-Engineer-Demo-Initial-Settings-and-JVM-Tunning/cloudbees-java-heap-memory-best-practices.jpg)
</Frame>

<Frame>
  ![The image shows a webpage from CloudBees documentation, detailing recommended JVM specifications for CloudBees CI, including heap size and garbage collection settings.](https://kodekloud.com/kk-media/image/upload/v1752870820/notes-assets/images/Certified-Jenkins-Engineer-Demo-Initial-Settings-and-JVM-Tunning/cloudbees-ci-jvm-specifications.jpg)
</Frame>

## 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:

```bash theme={null}
sudo systemctl edit jenkins
```

Populate the editor with:

```ini theme={null}
[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:

```bash theme={null}
ps aux | grep -i jenkins
```

You might see something like:

```bash theme={null}
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:

```bash theme={null}
sudo systemctl restart jenkins
ps aux | grep -i jenkins
```

Expected output:

```bash theme={null}
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.

<Callout icon="triangle-alert" color="#FF6B6B">
  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.
</Callout>

## References

* [Jenkins Configuration as Code](https://github.com/jenkinsci/configuration-as-code-plugin)
* [CloudBees Jenkins Platform Documentation](https://docs.cloudbees.com/)
* [Kubernetes Best Practices for JVMs](https://kubernetes.io/docs/tasks/run-application/run-stateless-application-deployment/)

<CardGroup>
  <Card title="Watch Video" icon="video" cta="Learn more" href="https://learn.kodekloud.com/user/courses/certified-jenkins-engineer/module/7ab00946-0edd-4a13-b5c8-1b5001779f1c/lesson/0507a69a-548d-4a0d-8027-0afd7750aa98" />
</CardGroup>