🚨 Jenkins Error: 'Disk space is below threshold of 1.00 GiB. Only 0.50 GiB out of 40.00 GiB left on /var/jenkins_home' — Cause, Fix, and Troubleshooting Guide

Overview

Jenkins runs built-in Node Monitors that check each controller and agent for free disk, temp space, and memory. When free disk on a monitored path drops below the configured threshold, Jenkins marks the node offline so new builds won’t be scheduled onto a node that’s about to fail:

Disk space is below threshold of 1.00 GiB. Only 0.50 GiB out of 40.00 GiB left on /var/jenkins_home

The node’s status flips to offline with this as the reason. This is a protective action, not a crash — Jenkins is telling you the node is nearly full. Left unattended, a genuinely full disk causes far worse failures: corrupt builds, failed checkouts, and dropped agents. The fix is to reclaim space and prevent the bloat from recurring.

Symptoms

• A node (controller or agent-01) shows offline in Manage Jenkins → Nodes with the message above.
• New builds queue but never start because no eligible node is online for the label.
• Builds that were running on the node may fail or the agent may disconnect.
• df -h on the host confirms /var/jenkins_home (or the agent workspace volume) is near 100% used.
• The number climbs steadily over days/weeks — classic accumulation, not a sudden spike.

Common Root Causes

• Old build records and logs — every build keeps its console log, build.xml, and metadata under jobs/<name>/builds/. Without a discarder, these accumulate forever.
• Archived artifacts — large archiveArtifacts outputs (JARs, images, reports) pile up per build and are never pruned.
• Stale workspaces — reused workspaces under workspace/ keep checkouts, node_modules, target/, and downloaded dependencies between builds.
• Docker layers and volumes — builds that run docker build/docker run on the agent leave dangling images, build cache, and volumes that grow without bound.
• Temp files — /tmp (or $JENKINS_TMPDIR) fills with unpacked tools, caches, and leftover files from killed builds.
• Threshold too high for a small volume — a 40 GiB volume with a 1 GiB threshold trips easily; the disk really is tight, or the threshold is mis-sized.
• Manage Old Data / obsolete plugin data — leftover records from removed plugins and old data formats consume space and slow the controller.

How to diagnose

Confirm the real usage on the host, then find what’s consuming it. On the affected node:

df -h /var/jenkins_home                 # confirm the near-full path
du -h --max-depth=1 /var/jenkins_home | sort -rh | head -20
# Usual suspects:
du -sh /var/jenkins_home/jobs/*/builds  2>/dev/null | sort -rh | head
du -sh /var/jenkins_home/workspace/*    2>/dev/null | sort -rh | head

Check Docker if the agent builds images:

docker system df           # reclaimable images, containers, cache, volumes

Review the node monitor configuration and the current reason in the UI:

Manage Jenkins → Nodes → agent-01 → shows the offline reason
Manage Jenkins → System → "Disk space monitoring" / free space thresholds
Manage Jenkins → Old Data  → leftover data from removed/updated plugins

You can also read the free space a monitor sees from the Script Console:

// Read-only: what the disk-space monitor reports per node
import hudson.node_monitors.DiskSpaceMonitor
Jenkins.instance.nodes.each { n ->
  def d = DiskSpaceMonitor.DESCRIPTOR.get(n.toComputer())
  println "${n.nodeName}: ${d?.size ? (d.size/1024/1024/1024) + ' GiB free' : 'n/a'}"
}

Fixes

1. Reclaim space now

Free enough to bring the node back online, then address the cause. On the host:

# Prune Docker (safe: removes dangling images, stopped containers, unused cache)
docker system prune -af --volumes
# Clear Jenkins temp
rm -rf "${JENKINS_TMPDIR:-/tmp}"/jenkins* 2>/dev/null

Do not hand-delete files inside jobs/*/builds while Jenkins is running — use the build discarder or the CLI so Jenkins updates its indexes.

2. Add a build discarder (logRotator) to every job

Cap how many builds and artifacts each job keeps. In a declarative pipeline:

options {
  buildDiscarder(logRotator(
    numToKeepStr: '30',        // keep last 30 build records
    daysToKeepStr: '30',       // and/or last 30 days
    artifactNumToKeepStr: '5', // keep artifacts for only the last 5 builds
    artifactDaysToKeepStr: '7'
  ))
}

For existing jobs at scale, set a global default via Manage Jenkins or a startup Groovy script so every job inherits a discarder.

3. Clean the workspace after builds

Use the Workspace Cleanup plugin to delete the workspace when the build ends, so checkouts and build output don’t persist:

post {
  always {
    cleanWs()   // requires the Workspace Cleanup plugin (ws-cleanup)
  }
}

For jobs that must keep a warm workspace, at least clean before checkout with the CleanBeforeCheckout SCM extension instead.

4. Right-size the disk-space threshold

If the volume is small and the default 1 GiB threshold is too aggressive (or too lax), tune it in Manage Jenkins → System → Disk Space Monitoring. You can set the free-space and free-temp-space thresholds, e.g. 2GiB on a controller, or use a percentage. Raising the threshold does not create space — it only changes when Jenkins protects the node. Fix the bloat first; set the threshold to give yourself a safety margin.

5. Clear obsolete data and unused plugins

Visit Manage Jenkins → Old Data and discard leftover records from removed/updated plugins. Remove plugins you no longer use. This trims $JENKINS_HOME and speeds controller startup.

6. Move heavy storage off the root volume

If artifacts are legitimately large, archive to external storage (S3/artifact repository) instead of $JENKINS_HOME, or mount builds/, workspace/, and Docker’s data-root on a larger dedicated volume so growth doesn’t threaten the controller.

What to watch out for

• The message is a warning that saved you — the node went offline before the disk fully filled. Don’t just raise the threshold to silence it; reclaim space.
• Set a build discarder on every job. A single high-frequency job with no discarder can fill a volume on its own.
• Docker build cache is the most common silent consumer on build agents — schedule docker system prune (with care) or use ephemeral agents.
• A full agent disk also causes agents to disconnect mid-build — treat recurring disk alerts and agent drops as the same problem.
• Monitor free space proactively (Prometheus/node_exporter, or the Jenkins metrics plugin) so you act before a node goes offline.

Related

• Jenkins Error: Agent went offline during the build — a full agent disk is a common reason agents drop mid-build.
• Jenkins Error: Waiting for next available executor — when a node goes offline for disk, builds pile up waiting for an executor.
• GitLab CI: no space left on device — the equivalent runner-disk-full failure on GitLab CI.