Skip to main content
If Jenkins on your local machine returns an HTTP 500 or the web UI fails to load, the root cause is often a JVM heap exhaustion. This guide shows how to identify a Java heap space OutOfMemoryError, locate where JVM options are configured for a systemd-managed Jenkins service, and safely increase JVM heap settings. Problem symptom
  • The Jenkins web UI at http://localhost:8080 returned an HTTP 500 when loading /login.
  • Server logs show java.lang.OutOfMemoryError: Java heap space.
Example HTTP error returned by Jenkins:
Confirming via logs Search the system journal for heap-related errors to confirm the OutOfMemoryError:
Example log lines you may encounter:
Where are the JVM options configured? On a systemd-managed Jenkins installation, JVM and environment options are normally supplied by the service unit or a drop-in override. Inspect the current service configuration with:
Example snippet returned by systemctl cat:
To create or edit a drop-in file (safe method to override only specific settings) use:
This opens an editor and writes a drop-in such as /etc/systemd/system/jenkins.service.d/override.conf. The service must be restarted for changes to take effect. Recommended heap sizes Below are general recommendations for Jenkins JVM heap sizing. Use these as starting points and adjust based on the number of plugins, jobs, and concurrent activity.
A screenshot of CloudBees CI documentation titled "Recommended specifications for CloudBees CI," showing a section about Heap size with a table of initial/maximum heap sizes and garbage collection recommendations. The page includes a left navigation menu and a "Submit Feedback" button.
Important: JVM and container behavior
If running Jenkins inside containers (Docker, Kubernetes), prefer container-aware JVM options such as -XX:+UseContainerSupport (enabled by default on modern OpenJDK) and percentage-based options like -XX:MaxRAMPercentage / -XX:InitialRAMPercentage. These respect container memory limits better than fixed -Xms/-Xmx values.
Editing the systemd drop-in to increase heap If your current JVM flags are too small (for example -Xms90M -Xmx90M), increase them in the drop-in. Example existing configuration:
To raise the heap to 1 GiB, run:
Then add the following to the editor and save:
After saving, you should see a confirmation such as:
Restarting Jenkins to apply the change As a best practice, restart the service after any systemd unit change:
Verify the running process and JVM options Before restarting, you can inspect the running Jenkins process to observe previously active JVM flags:
After restart, confirm the new flags are active:
Result After increasing the heap from 90M to 1G and restarting Jenkins, the login page loaded and I could authenticate successfully. Continue to monitor logs and heap usage to ensure the new values remain sufficient under expected load. Best practices and guidelines
  • For bare-metal or VM installs, tuning -Xms/-Xmx is straightforward and effective.
  • For containerized Jenkins, prefer container-aware JVM options (-XX:+UseContainerSupport, -XX:MaxRAMPercentage, -XX:InitialRAMPercentage) and set appropriate container memory limits.
  • Avoid setting a single JVM heap above ~16 GiB; scale horizontally instead of increasing a single JVM heap beyond practical limits.
  • After any systemd unit change, restart the service and verify process arguments (ps) and logs (journalctl -u jenkins).
  • Monitor garbage collection and heap usage; increasing heap can alter GC behavior — if GC pauses are problematic, consider GC tuning or changing GC algorithms.
Do not edit the packaged /usr/lib/systemd/system/jenkins.service file directly. Use systemctl edit jenkins to create a drop-in override so packaged updates or upgrades do not overwrite your custom settings.
Links and references

Watch Video