Fix Jenkins java.lang.OutOfMemoryError: PermGen Space (Controller, Agents, and Build Tools)

Originally published on 2015-09-03; fully revised and updated.

If Jenkins jobs fail with java.lang.OutOfMemoryError: PermGen space, the practical fix is to apply JVM memory flags in the correct scope: Jenkins controller, Jenkins agent, or the build tool process itself. This walkthrough explains where to set those options on Linux and Windows, how to validate them, and what to do on modern Java versions where PermGen no longer exists.

What this Jenkins error usually means

The original error references PermGen, which applies to older JVMs (typically Java 7 and earlier). In Jenkins environments, failures may come from different JVMs, not only the Jenkins controller process.

• Controller JVM: Jenkins service itself runs out of memory.
• Agent JVM: build node (SSH/JNLP/service) launches with low memory flags.
• Build tool JVM: Maven/Gradle/Sonar runner process is constrained.

For Java 8 and newer, use Metaspace-related flags instead of PermGen flags.

Triage workflow before changing memory settings

flowchart TD
    A[Build fails with OutOfMemoryError] --> B{Failure location}
    B --> C[Controller logs]
    B --> D[Agent logs]
    B --> E[Build tool output]
    C --> F[Check Java major version]
    D --> F
    E --> F
    F --> G{Java 7 or earlier}
    G -- yes --> H[Use Xmx and MaxPermSize]
    G -- no --> I[Use Xmx and MaxMetaspaceSize]
    H --> J[Apply at controller or agent or tool scope]
    I --> J
    J --> K[Restart affected process]
    K --> L[Re-run build and monitor]

Where to set JVM options in Jenkins environments

Configuration examples

Set environment variables in Linux shell profiles

The original post used ~/.bash_profile. Keep in mind this affects only processes that inherit that shell environment.

# Java 7 and earlier (PermGen)
export JAVA_OPTS="-XX:MaxPermSize=512m -Xms512m -Xmx1024m"
export GRADLE_OPTS="-XX:MaxPermSize=512m"
export SONAR_RUNNER_OPTS="-Xmx512m -XX:MaxPermSize=512m"

# Java 8+ (Metaspace)
export JAVA_OPTS="-Xms512m -Xmx1024m -XX:MaxMetaspaceSize=512m"
export GRADLE_OPTS="-Xmx1024m -XX:MaxMetaspaceSize=512m"
export SONAR_RUNNER_OPTS="-Xmx512m -XX:MaxMetaspaceSize=512m"Code language: PHP (php)

Set controller JVM flags in Jenkins service config

From the original guidance: RedHat-based installs often use /etc/sysconfig/jenkins and Debian/Ubuntu installs often use /etc/default/jenkins.

# /etc/sysconfig/jenkins (example)
JENKINS_JAVA_OPTIONS="-XX:MaxPermSize=512m -Xms512m -Xmx1024m"

# /etc/default/jenkins (example)
JAVA_ARGS="-XX:MaxPermSize=512m -Xms512m -Xmx1024m"Code language: PHP (php)

If your Jenkins runtime is Java 8 or newer, replace -XX:MaxPermSize with a Metaspace limit such as -XX:MaxMetaspaceSize.

Set job environment in Jenkins global configuration

• Go to Manage Jenkins → Configure System.
• Under global environment settings, add name/value pairs such as JAVA_OPTS or GRADLE_OPTS.
• Use this for job-level runtime tools when service-level tuning is not enough.

Name: JAVA_OPTS
Value: -XX:MaxPermSize=512m -Xms512m -Xmx1024m

Name: GRADLE_OPTS
Value: -XX:MaxPermSize=512mCode language: HTTP (http)

Agent-specific JVM options (SSH/JNLP/Windows service)

Agent configuration depends on launch mode. For Windows JNLP service agents, JVM arguments are commonly set in the agent-side jenkins.xml.

<service>
  <id>jenkins-agent</id>
  <name>Jenkins Agent</name>
  <arguments>-jnlpUrl http://jenkins.example/computer/agent/slave-agent.jnlp -secret ******** -workDir C:\\Jenkins</arguments>
  <executable>java</executable>
  <logmode>rotate</logmode>
  <onfailure action="restart"/>
  <!-- Add JVM flags in the executable arguments per your service wrapper format -->
</service>Code language: HTML, XML (xml)

Verify the applied settings

After changing options, restart the affected process (controller or agent), then confirm runtime flags from the host.

# Confirm Jenkins Java process arguments
ps -ef | grep -i jenkins

# If jcmd is available, inspect effective JVM flags
jcmd $(pgrep -f jenkins | head -n 1) VM.flags

# Confirm environment options in current shell/job context
echo "$JAVA_OPTS"
echo "$GRADLE_OPTS"Code language: PHP (php)

References from the original post

• http://stackoverflow.com/questions/18000841/jenkins-java-lang-outofmemoryerror-permgen-space
• https://wiki.jenkins-ci.org/display/JENKINS/Builds+failing+with+OutOfMemoryErrors
• https://cloudbees.zendesk.com/hc/en-us/articles/204264000-Why-do-I-receive-java-lang-OutOfMemoryError-PermGen-space
• http://stackoverflow.com/questions/14762162/how-do-i-give-jenkins-more-heap-space-when-its-running-as-a-daemon-on-ubuntu
• http://javarevisited.blogspot.nl/2011/09/javalangoutofmemoryerror-permgen-space.html
• https://plumbr.eu/outofmemoryerror/permgen-space

Best practices

• Identify which JVM is failing before increasing memory globally.
• Use version-appropriate flags: PermGen for older JVMs, Metaspace for Java 8+.
• Prefer the narrowest scope first (specific agent/tool) before changing controller-wide defaults.
• After each change, restart the affected process and verify effective flags from process output.
• Track memory changes in configuration management so rollback is easy and consistent across nodes.

Rajesh Kumar

I’m Rajesh Kumar, a DevOps, SRE, DevSecOps, Cloud, and Platform Engineering expert passionate about sharing practical knowledge, real-world experiences, and industry best practices. I have worked at Cotocus and regularly write about technology, travel, investing, health, product reviews, and digital marketing through my various platforms.

I publish technical articles at DevOps School, travel stories at Holiday Landmark, stock market insights at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow, and SEO and digital marketing strategies at Wizbrand.