Jenkins Plugin Install Failed

The Problem

You're trying to install a plugin through the Jenkins UI, and it fails. Maybe you see a timeout, a checksum error, or a cryptic message about dependencies:

``` Failed to install plugin 'git-plugin' Checksum verification failed for /var/lib/jenkins/plugins/git.jpi

# Or Failed to install plugin 'workflow-aggregator' Dependency workflow-step-api (2.10) doesn't exist

# Or simply Installation failed. See log for details. ```

Meanwhile, the plugin manager shows the spinning icon forever, or errors out after a long wait. Let's fix this.

Checking the Update Center

Jenkins plugins come from the Jenkins Update Center. If you can't reach it, nothing installs. Test connectivity:

```bash # Test update center connectivity curl -I https://updates.jenkins.io/update-center.json

# Check if Jenkins can reach it curl -v http://localhost:8080/pluginManager/available 2>&1 | grep -i "HTTP/" ```

If this times out or fails, you have network issues.

Proxy Configuration

If Jenkins sits behind a corporate proxy:

Via UI: Go to Manage Jenkins > Plugins > Advanced > Proxy Configuration

Via config file: Edit /var/lib/jenkins/proxy.xml:

<?xml version='1.0' encoding='UTF-8'?>
<proxyConfig>
  <name>proxy.company.com</name>
  <port>8080</port>
  <userName>proxyuser</userName>
  <password>{encrypted_password}</password>
  <noProxyHost>internal.company.com,*.internal.company.com</noProxyHost>
</proxyConfig>

Via Java args:

# Add to JAVA_OPTS in systemd override
Environment="JAVA_OPTS=-Dhttp.proxyHost=proxy.company.com -Dhttp.proxyPort=8080 -Dhttps.proxyHost=proxy.company.com -Dhttps.proxyPort=8080 -Dhttp.nonProxyHosts='internal.company.com|*.internal.company.com'"

Update Center URL Issues

Sometimes the update center URL is outdated or unreachable. Change it:

Via UI: Go to Manage Jenkins > Plugins > Advanced > Update Site

Default: https://updates.jenkins.io/update-center.json

Try alternatives: - https://mirrors.tuna.tsinghua.edu.cn/jenkins/updates/update-center.json (China) - https://ftp-nyc.osuosl.org/pub/jenkins/updates/update-center.json (US East) - https://ftp-chi.osuosl.org/pub/jenkins/updates/update-center.json (US Central)

Via script console:

// Script Console - change update center
def uc = Jenkins.instance.getUpdateCenter()
uc.getSite("default").url = new URL("https://mirrors.tuna.tsinghua.edu.cn/jenkins/updates/update-center.json")
uc.getSite("default").updateDirectly()

Dependency Resolution Issues

Plugins depend on other plugins. If a required dependency is missing or has the wrong version, installation fails.

Check Dependencies Manually

```bash # Use Jenkins CLI to check dependencies java -jar jenkins-cli.jar -s http://localhost:8080 list-plugins | grep -A 5 "plugin-name"

# Or via script console ```

// Script Console - show plugin dependencies
Jenkins.instance.pluginManager.plugins.each { plugin ->
    println "${plugin.shortName}:${plugin.version}"
    plugin.dependencies.each { dep ->
        println "  - ${dep.shortName}:${dep.version}"
    }
}

Install Dependencies First

Sometimes you need to install dependencies before the main plugin:

1. 1.Go to Manage Jenkins > Plugins > Available
2. 2.Search for and install the dependency first
3. 3.Restart Jenkins
4. 4.Install the main plugin

Common dependency chains: - workflow-aggregator requires workflow-step-api, workflow-api, workflow-support - git requires git-client, scm-api - kubernetes requires kubernetes-client-api, snakeyaml-api

Manual Plugin Installation

When the UI fails, install plugins manually.

Method 1: Download and Install

```bash # Find the plugin download URL # Format: https://updates.jenkins.io/download/plugins/{plugin-name}/{version}/{plugin-name}.hpi

# Example for Git plugin cd /var/lib/jenkins/plugins sudo wget https://updates.jenkins.io/download/plugins/git/5.0.0/git.hpi

# Rename to .jpi (Jenkins Plugin Archive) sudo mv git.hpi git.jpi

# Set ownership sudo chown jenkins:jenkins git.jpi

# Restart Jenkins sudo systemctl restart jenkins ```

Method 2: Copy from Working Instance

If you have another Jenkins with the plugin:

```bash # On working instance cd /var/lib/jenkins/plugins tar czf plugin-bundle.tar.gz plugin-name/ plugin-name.jpi

# Copy to problem instance and extract cd /var/lib/jenkins/plugins sudo tar xzf plugin-bundle.tar.gz sudo chown -R jenkins:jenkins plugin-name* sudo systemctl restart jenkins ```

Method 3: Use Jenkins CLI

```bash # Download CLI jar wget http://localhost:8080/jnlpJars/jenkins-cli.jar

# Install plugin java -jar jenkins-cli.jar -s http://localhost:8080 -auth user:apiToken install-plugin git

# List installed plugins java -jar jenkins-cli.jar -s http://localhost:8080 -auth user:apiToken list-plugins ```

Checksum and Security Errors

If you see checksum verification errors:

Checksum verification failed for /var/lib/jenkins/plugins/git.jpi
Expected: abc123...
Actual: def456...

This often happens with: - Interrupted downloads - Mirror synchronization issues - Man-in-the-middle attacks (legitimate security block)

Bypass Checksum (Development Only!)

For development or when you trust the source:

// Script Console - disable checksum verification (restart required)
import hudson.model.UpdateSite;
UpdateSite site = Jenkins.instance.getUpdateCenter().getById("default")
site.isAllowSignatureValidation() // Check current
// Can't easily change this, but you can manually install

Re-download the Plugin

```bash # Remove the corrupted file sudo rm /var/lib/jenkins/plugins/git.jpi sudo rm -rf /var/lib/jenkins/plugins/git/

# Clear any cached downloads sudo rm -rf /var/lib/jenkins/updates/

# Restart and try again sudo systemctl restart jenkins ```

Offline Installation

If Jenkins truly cannot reach the internet:

Create Offline Plugin Bundle

On a connected machine:

```bash # Download plugin and all dependencies # Use https://plugins.jenkins.io/ to find dependencies

mkdir jenkins-plugins cd jenkins-plugins

# Download each plugin wget https://updates.jenkins.io/download/plugins/git/5.0.0/git.hpi wget https://updates.jenkins.io/download/plugins/git-client/4.0.0/git-client.hpi # ... download all dependencies

# Create bundle tar czf jenkins-plugins.tar.gz *.hpi ```

Transfer to offline Jenkins:

cd /var/lib/jenkins/plugins
sudo tar xzf jenkins-plugins.tar.gz
for f in *.hpi; do mv "$f" "${f%.hpi}.jpi"; done
sudo chown jenkins:jenkins *.jpi
sudo systemctl restart jenkins

Use Plugin Installation Manager Tool

For more sophisticated offline setups, use the Jenkins Plugin Installation Manager:

```bash # Download tool wget https://github.com/jenkinsci/plugin-installation-manager-tool/releases/latest/download/jenkins-plugin-manager.jar

# Create plugin list cat > plugins.txt <<EOF git:5.0.0 workflow-aggregator:596.v8c21c963d660 kubernetes:1.31.0 EOF

# Download all plugins java -jar jenkins-plugin-manager.jar --plugin-file plugins.txt --plugin-download-directory ./plugins

# Copy to Jenkins sudo cp ./plugins/*.jpi /var/lib/jenkins/plugins/ sudo chown jenkins:jenkins /var/lib/jenkins/plugins/*.jpi ```

Verifying Installation

After installing:

```bash # Check plugin is loaded ls -la /var/lib/jenkins/plugins/git.jpi ls -la /var/lib/jenkins/plugins/git/

# Check in logs grep -i "plugin git" /var/log/jenkins/jenkins.log | tail -5

# Via CLI java -jar jenkins-cli.jar -s http://localhost:8080 list-plugins | grep git ```

1. 1.In the UI:
2. 2.Go to Manage Jenkins > Plugins > Installed
3. 3.Search for the plugin name
4. 4.Verify version matches expected
5. 5.Check for any warnings about missing dependencies

Common Plugin Installation Issues