alibaba/canal · error · RuntimeException

load extension jar failed!

Error message

load extension jar failed!

What it means

Error "load extension jar failed!" thrown in alibaba/canal.

Source

Thrown at client-adapter/common/src/main/java/com/alibaba/otter/canal/client/adapter/support/ExtensionLoader.java:282

        // 1. plugin folder，customized extension classLoader （jar_dir/plugin）
        String dir = File.separator + this.getJarDirectoryPath() + File.separator + "plugin";

        File externalLibDir = new File(dir);
        if (!externalLibDir.exists()) {
            externalLibDir = new File(File.separator + this.getJarDirectoryPath() + File.separator + "canal-adapter"
                                      + File.separator + "plugin");
        }
        logger.info("extension classpath dir: " + externalLibDir.getAbsolutePath());
        if (externalLibDir.exists()) {
            File[] files = externalLibDir.listFiles((dir1, name) -> name.endsWith(".jar"));
            if (files != null) {
                for (File f : files) {
                    URL url;
                    try {
                        url = f.toURI().toURL();
                    } catch (MalformedURLException e) {
                        throw new RuntimeException("load extension jar failed!", e);
                    }

                    ClassLoader parent = Thread.currentThread().getContextClassLoader();
                    URLClassLoader localClassLoader;
                    if (classLoaderPolicy == null || "".equals(classLoaderPolicy)
                        || DEFAULT_CLASSLOADER_POLICY.equalsIgnoreCase(classLoaderPolicy)) {
                        localClassLoader = new URLClassExtensionLoader(new URL[] { url });
                    } else {
                        localClassLoader = new URLClassLoader(new URL[] { url }, parent);
                    }

                    loadFile(extensionClasses, CANAL_DIRECTORY, localClassLoader);
                    loadFile(extensionClasses, SERVICES_DIRECTORY, localClassLoader);
                }
            }
        }
        // 只加载外部spi, 不加载classpath
        // 2. load inner extension class with default classLoader

View on GitHub (pinned to 87be50e876)

Solutions

1. Verify the extension jar path exists and is readable by the adapter launcher process.
2. Check the jar is a valid, non-corrupted file and compatible with the running JVM version.

When it happens

Trigger: Thrown at client-adapter/common/src/main/java/com/alibaba/otter/canal/client/adapter/support/ExtensionLoader.java:282 when the library encounters an invalid state.

Common situations: Failed to load an extension jar. Check the jar path, readability, and that it does not conflict with already-loaded classes; fail startup rather than running with partial plugins.

AI-assisted analysis of alibaba/canal@87be50e876 (2026-08-14). Data as JSON: /api/errors/9307e52d489caba9. Report an issue: GitHub.