SonarSource/sonarqube · critical · IllegalStateException

Fail to create classloader for plugin [%s]

Error message

Fail to create classloader for plugin [%s]

What it means

SonarQube's PluginClassloaderFactory throws this IllegalStateException during plugin classloader construction when a plugin classloader definition references a basePluginKey for which no classloader exists in the built map. This means the definition depends on a base plugin that is not loaded (missing, unloaded, or wrong key). It is an internal invariant check guarding the plugin isolation/isolation-by-key loading model.

Source

Thrown at sonar-core/src/main/java/org/sonar/core/platform/PluginClassloaderFactory.java:112

    // export the resources to all other plugins
    builder.setExportMask(newDef.getBasePluginKey(), newDef.getExportMask().build());
    for (PluginClassLoaderDef other : allPlugins) {
      if (!other.getBasePluginKey().equals(newDef.getBasePluginKey())) {
        builder.addSibling(newDef.getBasePluginKey(), other.getBasePluginKey(), Mask.ALL);
      }
    }
  }

  /**
   * Builds classloaders and verifies that all of them are correctly defined
   */
  private static Map<PluginClassLoaderDef, ClassLoader> build(Collection<PluginClassLoaderDef> defs, ClassloaderBuilder builder) {
    Map<PluginClassLoaderDef, ClassLoader> result = new HashMap<>();
    Map<String, ClassLoader> classloadersByBasePluginKey = builder.build();
    for (PluginClassLoaderDef def : defs) {
      ClassLoader classloader = classloadersByBasePluginKey.get(def.getBasePluginKey());
      if (classloader == null) {
        throw new IllegalStateException(String.format("Fail to create classloader for plugin [%s]", def.getBasePluginKey()));
      }
      result.put(def, classloader);
    }
    return result;
  }

  ClassLoader baseClassLoader() {
    return getClass().getClassLoader();
  }

  private static URL fileToUrl(File file) {
    try {
      return file.toURI().toURL();
    } catch (MalformedURLException e) {
      throw new IllegalArgumentException(e);
    }
  }

View on GitHub (pinned to 184c821202)

Solutions

1. Verify the base plugin referenced by the failing plugin key is present in the plugins directory and listed in the loaded plugins.
2. Check startup logs for earlier plugin load failures that removed the base plugin before classloader construction.
3. Ensure the plugin's build declares the basePluginKey consistently (plugin key in its sonar-plugin packaging descriptor).
4. Upgrade or reinstall the dependent plugin to a version compatible with the installed SonarQube version.

Example fix

// before (definition references missing base plugin)
new PluginClassLoaderDef("my-plugin", "nonexistent-base", ...);
// after
new PluginClassLoaderDef("my-plugin", "base-plugin-key", ...); // key must exist among loaded plugins

Set<String> loadedKeys = builder.build().keySet();
for (PluginClassLoaderDef def : defs) {
  if (!loadedKeys.contains(def.getBasePluginKey())) {
    throw new IllegalArgumentException("Base plugin not loaded: " + def.getBasePluginKey());
  }
}

// IllegalStateException is unchecked; pre-validate base plugin keys before create()
try {
  factory.create(defs);
} catch (IllegalStateException e) {
  log.error("Plugin dependency missing: {}", e.getMessage());
}

When it happens

Trigger: Calling PluginClassloaderFactory.create() with PluginClassLoaderDef entries whose getBasePluginKey() is absent from the map returned by the ClassloaderBuilder.build() (e.g. a plugin declares a dependency on a base plugin that is not installed or failed to load).

Common situations: A plugin requiring a base plugin (like 'api' from a sonar-plugin dependency) that was removed from the plugins directory; corrupted plugin ordering; a plugin renamed/re-keyed so dependent plugins point at a stale key.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• No cache entry found for key:
• Virtual thread already started
• I18n classloader does support only resources, but not classe
• Fail to extract plugin metadata from file:
• Failed to read SARIF report at '%s': %s

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