Resolve Jenkins Plugin Load Errors by Disabling Incompatible Plugins

Jenkins plugins often require specific versions of Jenkins to function. If your log shows errors like Jenkins (2.479.1) or higher required or Update required: [Plugin Name] to be updated to, it means installed plugins are incompatible with your current Jenkins version or require a newer version. Here's how to resolve this by disabling problematic plugins.

Failed to load: [Plugin Name] - Jenkins (X.X.X) or higher required

Failed to load: Matrix Authorization Strategy Plugin (matrix-auth 3.2.5)
 - Update required: Folders Plugin (cloudbees-folder 6.955.v81e2a_35c08d3) to be updated to 6.976.v4dc79fb_c458d or higher

Quick fix:

touch [Plugin Name].jpi.disabled

  1. Stop Jenkins: Before making any file changes, ensure that your Jenkins instance is completely shut down. This helps prevent data corruption or partial plugin loads during the update.

  2. Access the Plugin Directory: In a standard Docker-based Jenkins setup, navigate to the /var/jenkins_home/plugins directory. On non-Docker installations, the location may vary but is typically found under the Jenkins home directory.

    shell cd /var/jenkins_home/plugins

  3. Identify Incompatible Plugins: From your error logs (found in jenkins.log), pinpoint which plugins are causing the Failed to load errors. You can use grep to find these errors:

    shell grep -E "Failed to load:|Update required:" jenkins.log

    This command will show all plugin load failures and update requirements in your log file. Typically, these errors arise when the plugin requires a newer (or older) Jenkins core than the one you're running.

  4. Disable Problematic Plugins: For each problematic plugin, append .disabled to the file's existing .jpi or .hpi extension. For instance, example-plugin.jpi becomes example-plugin.jpi.disabled.

    shell touch example-plugin.jpi.disabled

  5. Restart Jenkins: Once you've renamed the problematic plugins, restart Jenkins. It will ignore any plugin file ending in .disabled and should start without errors related to those plugins.

    shell sudo systemctl restart jenkins

  6. Plan for Upgrades or Rollbacks: Because disabling plugins only treats the symptom, consider either upgrading Jenkins to a version compatible with these plugins, or rolling back the plugins themselves to versions that work with your Jenkins core. Regular maintenance and version alignment will minimize future issues.