{"record":{"id":"78fff707fd457a07","repo":"alibaba/canal","slug":"load-extension-jar-failed-78fff7","errorCode":null,"errorMessage":"load extension jar failed!","messagePattern":"load extension jar failed!","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"connector/core/src/main/java/com/alibaba/otter/canal/connector/core/spi/ExtensionLoader.java","lineNumber":285,"sourceCode":"            // 1. plugin folder，customized extension classLoader\n            // （jar_dir/plugin）\n            String dir = File.separator + this.getJarDirectoryPath() + spiDir; // +\n                                                                               // \"plugin\";\n\n            File externalLibDir = new File(dir);\n            if (!externalLibDir.exists()) {\n                externalLibDir = new File(File.separator + this.getJarDirectoryPath() + standbyDir);\n            }\n            logger.info(\"extension classpath dir: \" + externalLibDir.getAbsolutePath());\n            if (externalLibDir.exists()) {\n                File[] files = externalLibDir.listFiles((dir1, name) -> name.endsWith(\".jar\"));\n                if (files != null) {\n                    for (File f : files) {\n                        URL url;\n                        try {\n                            url = f.toURI().toURL();\n                        } catch (MalformedURLException e) {\n                            throw new RuntimeException(\"load extension jar failed!\", e);\n                        }\n\n                        ClassLoader parent = Thread.currentThread().getContextClassLoader();\n                        URLClassLoader localClassLoader;\n                        if (classLoaderPolicy == null || \"\".equals(classLoaderPolicy)\n                            || DEFAULT_CLASSLOADER_POLICY.equalsIgnoreCase(classLoaderPolicy)) {\n                            localClassLoader = new URLClassExtensionLoader(new URL[] { url });\n                        } else {\n                            localClassLoader = new URLClassLoader(new URL[] { url }, parent);\n                        }\n\n                        loadFile(extensionClasses, CANAL_DIRECTORY, localClassLoader);\n                        loadFile(extensionClasses, SERVICES_DIRECTORY, localClassLoader);\n                    }\n                }\n            }\n        }\n","sourceCodeStart":267,"sourceCodeEnd":303,"githubUrl":"https://github.com/alibaba/canal/blob/87be50e87686a3e8af08c368d0e1ffd1f59eb04a/connector/core/src/main/java/com/alibaba/otter/canal/connector/core/spi/ExtensionLoader.java#L267-L303","documentation":"Thrown by loadExtensionClasses when File.toURI().toURL() throws MalformedURLException while iterating plugin jars. This is a defensive guard around converting a discovered jar file into a URL for the per-jar URLClassExtensionLoader/URLClassLoader. In practice toURI().toURL() rarely fails; failure implies a path/URI the JVM cannot turn into a valid URL (encoding oddity, unusual filesystem).","triggerScenarios":"A jar file in the plugin/standby directory whose path yields a malformed URL via toURI().toURL(); exotic filesystem characters that break URI-to-URL conversion.","commonSituations":"Jar filename or directory path with characters that the URI/URL layer mishandles; symlink or NFS-mounted plugin dir producing an odd file: URI; running on a platform with unusual path encoding.","solutions":["Move/rename the offending jar so its absolute path uses plain ASCII alphanumeric/underscore/hyphen characters.","Ensure the plugin directory is a normal local filesystem path (avoid unusual mounts/symlinks).","Confirm the jar is a valid zip archive and not a truncated/corrupt file."],"exampleFix":"# before\nplugin dir contains: /opt/canal/plugin/producer@v2!.jar\n# after\nrename to: /opt/canal/plugin/producer-v2.jar","handlingStrategy":"validation","validationCode":"// Validate plugin jar paths before the loader scans them\nFile pluginDir = new File(pluginPath);\nFile[] jars = pluginDir.listFiles((d, n) -> n.endsWith(\".jar\"));\nif (jars != null) for (File f : jars) {\n    if (!f.toURI().toString().matches(\"^[A-Za-z0-9._:/\\\\-]+$\")) {\n        throw new IllegalStateException(\"unsafe jar path: \" + f);\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    loader.getExtension(name, spiDir, standbyDir);\n} catch (RuntimeException e) {\n    if (e.getMessage().contains(\"load extension jar failed\")) {\n        // rename offending jar to plain ASCII and retry\n    } else throw e;\n}","preventionTips":["Use plain ASCII names for plugin jars and directories.","Avoid exotic characters/spaces in the canal install path."],"tags":["spi","classpath","plugin","filesystem"],"backgroundTag":null,"analyzedSha":"87be50e87686a3e8af08c368d0e1ffd1f59eb04a","analyzedAt":"2026-08-14T04:30:11.918Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}