🚨 Jenkins Error: 'java.lang.NoClassDefFoundError: <fully/qualified/Class>' — Cause, Fix, and Troubleshooting Guide

Overview

A plugin action, build step, or page in Jenkins blows up with a class-loading failure. The JVM found a reference to a class but could not load its definition at runtime:

java.lang.NoClassDefFoundError: org/example/plugin/SomeHelper
	at io.jenkins.plugins.example.Builder.perform(Builder.java:...)
	at hudson.tasks.BuildStepMonitor$1.perform(BuildStepMonitor.java:...)
Caused by: java.lang.ClassNotFoundException: org.example.plugin.SomeHelper
	at jenkins.util.AntClassLoader.findClassInComponents(AntClassLoader.java:...)

NoClassDefFoundError almost always means a plugin dependency problem: a plugin needs a class that another plugin (or the Jenkins core API) was supposed to provide, but the providing plugin is missing, disabled, or a version too old to contain that class. It differs from ClassNotFoundException in that the class existed at compile time but is absent — or unloadable — at runtime, typically after a partial or mismatched plugin upgrade.

Symptoms

• A specific plugin feature (a build step, post-build action, or admin page) throws NoClassDefFoundError, while the rest of Jenkins works.
• The error appeared right after upgrading, downgrading, or installing a plugin — or after a core upgrade without restarting.
• Manage Jenkins > Plugins or the startup log shows warnings about a plugin failing to load or an unmet dependency.
• The stack trace’s missing class belongs to a different plugin than the one throwing the error.
• ClassNotFoundException appears as the Caused by: root of the NoClassDefFoundError.
• A pipeline step that used to work now fails only on this controller after a plugin change.

Common Root Causes

• Missing or disabled dependency plugin — Plugin A depends on Plugin B for the referenced class, but B is not installed, is disabled, or failed to load at startup.
• Version-mismatched dependency — Plugin B is installed but older than the version that introduced the class Plugin A calls, so the symbol is absent at runtime.
• Stale artifacts from a partial upgrade — an upgrade left an old .jpi/.jpi.pinned/.hpi or an un-exploded plugin directory behind, so the wrong classes load.
• Core vs plugin API mismatch — jenkins.war was upgraded (or downgraded) but a plugin compiled against a different core API expects a class that this core does not export.
• JDK version mismatch — Jenkins runs on a JDK the plugin was not built for; a class fails to link (e.g., a plugin needing Java 17 running under Java 11, or a removed internal JDK class).
• Change applied without a restart — plugins were installed/updated dynamically and a class-loading graph is only half-initialized until Jenkins restarts.

How to diagnose

The startup log is the source of truth for plugin load failures. Read the controller log from boot and look for plugins that failed to start or dependency warnings:

# Controller service log (or Manage Jenkins > System Log)
journalctl -u jenkins --since '30 min ago' | grep -iE 'failed to load|dependency|NoClassDef|ClassNotFound|Failed Loading plugin'

In the UI, open Manage Jenkins > Plugins > Installed and sort/scan for plugins flagged as failed or needing a dependency. Manage Jenkins > System Information lists every loaded plugin and its exact version, plus the active JDK — cross-check the version of the plugin that owns the missing class.

Identify which plugin the missing class belongs to. From the Script Console (Manage Jenkins > Script Console), inspect the loaded plugins and versions read-only:

// Read-only: list installed plugins and versions to spot the stale/missing one
Jenkins.instance.pluginManager.plugins.sort{ it.shortName }.each {
  println "${it.shortName} : ${it.version} : active=${it.isActive()}"
}

Confirm the JDK Jenkins is actually running under (not just what’s on PATH):

# Java version linked into the running Jenkins process
java -version
# Or check System Information > "java.version" in the UI

Finally, list the plugin directory for stale or duplicate artifacts:

ls -la "$JENKINS_HOME/plugins/" | grep -iE '\.jpi|\.hpi|\.pinned|\.bak'

Fixes

Fix 1: Install or enable the missing dependency at the required version

Map the missing class to its owning plugin (the plugin’s docs or the class’s package name tell you which), then in Manage Jenkins > Plugins > Available/Installed install or upgrade it to a version at or above what the calling plugin requires. Jenkins’ Plugins > Advanced page and the update center normally resolve declared dependencies automatically — use them rather than hand-dropping .hpi files.

Fix 2: Restart Jenkins to finalize the class graph

Dynamic install/upgrade often half-loads a plugin. A full restart re-resolves the dependency graph cleanly:

# Graceful: finish running builds, then restart
# Visit http://jenkins.example.com/safeRestart  (UI) — or:
sudo systemctl restart jenkins

safeRestart waits for in-flight builds; a hard restart is fine if the instance is already broken.

Fix 3: Remove stale plugin artifacts

If an upgrade left duplicates, stop Jenkins, remove the stale files, and restart so the current versions explode fresh:

sudo systemctl stop jenkins
cd "$JENKINS_HOME/plugins"
# Remove the exploded dir and any leftover backup for the affected plugin
rm -rf example-plugin/ example-plugin.jpi.bak
sudo systemctl start jenkins

Only delete artifacts for the specific plugin you identified — never wipe the whole directory on a live controller.

Fix 4: Align the JDK with plugin requirements

If System Information shows a JDK older or newer than the plugin (and core) support, switch Jenkins to a supported LTS JDK. Update the JENKINS_JAVA_CMD/JAVA_HOME used by the service, then restart:

# Example: point the Jenkins service at a supported JDK
sudo systemctl edit jenkins   # set Environment=JAVA_HOME=/usr/lib/jvm/temurin-17
sudo systemctl restart jenkins

Fix 5: Roll back a bad upgrade

If the error started immediately after upgrading one plugin, use Manage Jenkins > Plugins > Installed > (plugin) > Downgrade (or restore the previous .jpi) to the last-known-good version, restart, and pin it until a compatible set is available.

What to watch out for

• The class in the message usually belongs to a dependency plugin, not the one throwing the error — resolve the provider’s version, not the caller’s.
• Always restart after plugin changes; a dynamic update that “succeeded” can still leave a half-initialized classloader.
• Upgrade plugins and core as a coordinated set — mixing a new plugin with an old core (or vice versa) is the classic source of API-mismatch NoClassDefFoundError.
• Check the running JDK, not the shell PATH; a service can launch under a different Java than your terminal shows.
• Take a backup of $JENKINS_HOME/plugins before bulk upgrades so a rollback is a file restore, not a reinstall.
• Test plugin upgrades on a staging controller first; class-loading breakage often only surfaces when a specific job exercises the affected code path.

Related

• Jenkins Error: unable to resolve class — the Pipeline-side counterpart when Groovy cannot resolve a type at compile time.
• Jenkins Error: java.lang.OutOfMemoryError: Java heap space — another JVM-level failure that can follow a bad upgrade or misconfigured heap.
• Jenkins Error: FATAL: command execution failed — a remoting failure that can accompany plugin/classloader problems on agents.