jenkinsci/jenkins · critical · IOException

Failed to initialize

Error message

Failed to initialize

What it means

Thrown by ClassicPluginStrategy.load(PluginWrapper) when the plugin's initialization phase fails. After the plugin class is loaded and instantiated, Jenkins sets its servlet context and calls startPlugin, which invokes Plugin.start(). The catch(Throwable) deliberately swallows everything (Errors included) and rethrows as IOException so a broken plugin aborts loading cleanly rather than killing the boot. The original cause is always attached as the exception cause.

Source

Thrown at core/src/main/java/hudson/ClassicPluginStrategy.java:404

                    if (!(o instanceof Plugin)) {
                        throw new IOException(className + " doesn't extend from hudson.Plugin");
                    }
                    wrapper.setPlugin((Plugin) o);
                } catch (LinkageError | ClassNotFoundException e) {
                    throw new IOException("Unable to load " + className + " from " + wrapper.getShortName(), e);
                } catch (NoSuchMethodException | InstantiationException | IllegalAccessException | InvocationTargetException e) {
                    throw new IOException("Unable to create instance of " + className + " from " + wrapper.getShortName(), e);
                }
            }

            // initialize plugin
            try {
                Plugin plugin = wrapper.getPluginOrFail();
                plugin.setServletContext(pluginManager.context);
                startPlugin(wrapper);
            } catch (Throwable t) {
                // gracefully handle any error in plugin.
                throw new IOException("Failed to initialize", t);
            }
        } finally {
            Thread.currentThread().setContextClassLoader(old);
        }
    }

    public void startPlugin(PluginWrapper plugin) throws Exception {
        plugin.getPluginOrFail().start();
    }

    @Override
    public void updateDependency(PluginWrapper depender, PluginWrapper dependee) {
        DependencyClassLoader classLoader = findAncestorDependencyClassLoader(depender.classLoader);
        if (classLoader != null) {
            classLoader.updateTransitiveDependencies();
            LOGGER.log(Level.INFO, "Updated dependency of {0}", depender.getShortName());
        }
    }

View on GitHub (pinned to 2e228ff40b)

Solutions

1. Read the attached cause stack trace in the Jenkins log to identify which line of the plugin's start() threw.
2. Verify all plugin dependencies are installed at compatible versions (check the plugin's MANIFEST.MF dependencies against installed plugins).
3. Upgrade or downgrade the failing plugin to a version compatible with the running Jenkins core.
4. If you own the plugin, move risky init (network/DB) out of start() into a lazily-initialized or @PostConstruct method with try/catch, or fail soft.
5. Disable the plugin via the UI/cli (rename its .jpi to .jpi.disabled) to restore Jenkins boot, then diagnose.

Example fix

// before
@Override
public void start() throws Exception {
    connect(); // throws if DB down -> Jenkins fails to initialize
}
// after
@Override
public void start() {
    try { connect(); }
    catch (Exception e) { LOGGER.log(Level.WARNING, "deferring connection", e); }
}

null

null

try {
    jenkins.getPluginManager().getPlugin(shortName).getPlugin().start();
} catch (IOException e) {
    // 'Failed to initialize' — inspect e.getCause() for the plugin's real failure
    LOGGER.log(Level.SEVERE, "Plugin " + shortName + " failed to start", e.getCause());
}

When it happens

Trigger: Plugin.start() or PluginWithContext.start() throws any Throwable; setServletContext throws; the plugin subclass overrides start() and performs DB/IO/network init that fails; a static initializer or @PostConstruct on the plugin object throws during start().

Common situations: Plugin upgraded to a version whose start() requires a newer Jenkins core; plugin depends on a missing/incompatible other plugin or library; plugin reads a config file that is absent or corrupt on first load; plugin connects to an external service during start() that is unreachable.

Related errors

• {} doesn't extend from hudson.Plugin
• Cannot find the plugin instance: {0}
• Failed to load {}. The file does not exist
• Failed to load {}. It is not a file
• Failed to load {}

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