jenkinsci/jenkins · error · IOException

Failed to refresh extensions after installing some plugins

Error message

Failed to refresh extensions after installing some plugins

What it means

Thrown when Jenkins.get().refreshExtensions() fails with ExtensionRefreshException during plugin batch startup. This means newly installed plugins' extension components could not be registered — typically because of classloader conflicts, missing extension points, or @Extension-annotated classes that fail to instantiate. The original ExtensionRefreshException is wrapped.

Source

Thrown at core/src/main/java/hudson/PluginManager.java:1020

            }
            for (Dependency d : depender.getOptionalDependencies()) {
                PluginWrapper dependee = pluginsByName.get(d.shortName);
                if (dependee != null) {
                    // this plugin depends on the newly loaded one!
                    // recalculate dependencies!
                    getPluginStrategy().updateDependency(depender, dependee);
                    break;
                }
            }
        }

        // Redo who depends on who.
        resolveDependentPlugins();

        try {
            Jenkins.get().refreshExtensions();
        } catch (ExtensionRefreshException e) {
            throw new IOException("Failed to refresh extensions after installing some plugins", e);
        }
        for (PluginWrapper p : plugins) {
            //TODO:According to the postInitialize() documentation, one may expect that
            //p.getPluginOrFail() NPE will continue the initialization. Keeping the original behavior ATM
          p.getPluginOrFail().postInitialize();
        }

        // run initializers in the added plugins
        Reactor r = new Reactor(InitMilestone.ordering());
        Set<ClassLoader> loaders = plugins.stream().map(p -> p.classLoader).collect(Collectors.toSet());
        r.addAll(new InitializerFinder(uberClassLoader) {
          @Override
          protected boolean filter(Method e) {
            return !loaders.contains(e.getDeclaringClass().getClassLoader()) || super.filter(e);
          }
        }.discoverTasks(r));
        new InitReactorRunner().run(r);
      }

View on GitHub (pinned to 2e228ff40b)

Solutions

Examine the wrapped ExtensionRefreshException for which extension/component failed.
Ensure all transitive plugin dependencies are installed and version-compatible.
Upgrade Jenkins core to a version that supports the plugin's required extension APIs.
Remove the conflicting plugin and retry the batch install.

Example fix

// No direct application-level fix; the cause is in plugin/extension compatibility.
// Inspect logs:
// e.getCause() -> ExtensionRefreshException with component details

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-check: ensure all dependencies are installed and compatible
for (PluginWrapper.Dependency dep : p.getDependencies()) {
    PluginWrapper resolved = pluginManager.getPlugin(dep.shortName);
    if (resolved == null || (dep.version != null && resolved.getVersion().compareTo(new VersionNumber(dep.version)) < 0)) {
        throw new IllegalStateException("Missing or incompatible dependency: " + dep.shortName);
    }
}

Try / catch

try {
    pluginManager.start(pluginsToStart);
} catch (IOException e) {
    if (e.getCause() instanceof ExtensionRefreshException) {
        ExtensionRefreshException ere = (ExtensionRefreshException) e.getCause();
        listener.error("Extension refresh failed: " + ere.getMessage());
        // The problematic extension/component info is in ere
    } else {
        throw e;
    }
}

Prevention

Verify all transitive plugin dependencies are installed and version-compatible before batch start.
Upgrade Jenkins core to match plugin extension API requirements.
Test plugin batches on a staging instance before production.

When it happens

Trigger: After batch-installing plugins, calling refreshExtensions() encounters a component that cannot be loaded — class not found, incompatible API, or a constructor that throws.

Common situations: Installing a plugin that depends on an extension point API version not present in the running Jenkins, or a plugin whose @Extension classes have unsatisfied dependencies at instantiation time.

Related errors

AI-assisted analysis of jenkinsci/jenkins@2e228ff40b (2026-08-14). Data as JSON: /api/errors/2008a2fff338c8c6. Report an issue: GitHub.