SonarSource/sonarqube · critical · IllegalStateException

Fail to instantiate class

Error message

Fail to instantiate class [%s] of plugin [%s]

What it means

PluginClassLoader catches any Throwable other than UnsupportedClassVersionError during plugin main-class instantiation and wraps it in an IllegalStateException "Fail to instantiate class [%s] of plugin [%s]".

Solutions

1. Read the wrapped cause for the root failure (CNFE, NoSuchMethodError, etc.)
2. Reinstall the plugin jar (verify checksum and completeness)
3. Update the plugin to a version compatible with the platform
4. Check plugin configuration properties required by its constructor

try {
  instances = pluginClassLoader.load(def);
} catch (IllegalStateException e) {
  LOG.error("Plugin {} failed to load, skipping", pluginKey, e.getCause());
  // disable plugin and continue startup if platform allows
}

When it happens

Trigger: loadClass or newInstance() throws — missing main class (CNFE), constructor exception, NoClassDefFoundError for a missing dependency, security manager denial.

Common situations: Corrupted plugin jar; plugin main class constructor throws on bad configuration; missing transitive dependencies; plugin incompatible with platform API.

Related errors

• The plugin [ ] does not support Java
• A plugin is storing excessively large data in the following…
• Configuration error: property definition named
• ############################################################…
• Fail to initialize servlet filter: . Message:

AI-assisted analysis of SonarSource/sonarqube@184c821202 (2026-09-09). Data as JSON: /api/errors/5a21322324fd4208. Report an issue: GitHub.

Appendix: source

Thrown at sonar-core/src/main/java/org/sonar/core/platform/PluginClassLoader.java:139

   * @throws IllegalStateException if at least one plugin can't be correctly loaded
   */
  private static Map<String, Plugin> instantiatePluginClasses(Map<PluginClassLoaderDef, ClassLoader> classloaders) {
    // instantiate plugins
    Map<String, Plugin> instancesByPluginKey = new HashMap<>();
    for (Map.Entry<PluginClassLoaderDef, ClassLoader> entry : classloaders.entrySet()) {
      PluginClassLoaderDef def = entry.getKey();
      ClassLoader classLoader = entry.getValue();

      // the same classloader can be used by multiple plugins
      for (Map.Entry<String, String> mainClassEntry : def.getMainClassesByPluginKey().entrySet()) {
        String pluginKey = mainClassEntry.getKey();
        String mainClass = mainClassEntry.getValue();
        try {
          instancesByPluginKey.put(pluginKey, (Plugin) classLoader.loadClass(mainClass).getDeclaredConstructor().newInstance());
        } catch (UnsupportedClassVersionError e) {
          throw new IllegalStateException(String.format("The plugin [%s] does not support Java %s", pluginKey, SystemUtils.JAVA_VERSION), e);
        } catch (Throwable e) {
          throw new IllegalStateException(String.format("Fail to instantiate class [%s] of plugin [%s]", mainClass, pluginKey), e);
        }
      }
    }
    return instancesByPluginKey;
  }

  public void unload(Collection<Plugin> plugins) {
    for (Plugin plugin : plugins) {
      ClassLoader classLoader = plugin.getClass().getClassLoader();
      if (classLoader instanceof Closeable closeable && classLoader != classloaderFactory.baseClassLoader()) {
        try {
          closeable.close();
        } catch (Exception e) {
          LoggerFactory.getLogger(getClass()).error("Fail to close classloader " + classLoader.toString(), e);
        }
      }
    }
  }

View on GitHub (pinned to 184c821202)