{"record":{"id":"8600e0e2ae0db002","repo":"apache/pulsar","slug":"failed-to-load-the-extension-for-extension-name","errorCode":null,"errorMessage":"Failed to load the extension for extension name `${extensionName}`","messagePattern":"Failed to load the extension for extension name `(.+?)`","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"pulsar-proxy/src/main/java/org/apache/pulsar/proxy/extensions/ProxyExtensions.java","lineNumber":76,"sourceCode":"                        conf.getProxyExtensionsDirectory(), conf.getNarExtractionDirectory());\n\n        ImmutableMap.Builder<String, ProxyExtensionWithClassLoader> extensionsBuilder = ImmutableMap.builder();\n\n        conf.getProxyExtensions().forEach(extensionName -> {\n\n            ProxyExtensionMetadata definition = definitions.extensions().get(extensionName);\n            if (null == definition) {\n                throw new RuntimeException(\"No extension is found for extension name `\" + extensionName\n                    + \"`. Available extensions are : \" + definitions.extensions());\n            }\n\n            ProxyExtensionWithClassLoader extension;\n            try {\n                extension = ProxyExtensionsUtils.load(definition, conf.getNarExtractionDirectory());\n            } catch (IOException e) {\n                log.error().attr(\"extension\", extensionName).exception(e)\n                        .log(\"Failed to load the extension\");\n                throw new RuntimeException(\"Failed to load the extension for extension name `\" + extensionName + \"`\");\n            }\n\n            if (!extension.accept(extensionName)) {\n                extension.close();\n                log.error().attr(\"extension\", extensionName)\n                        .log(\"Malformed extension found\");\n                throw new RuntimeException(\"Malformed extension found for extension name `\" + extensionName + \"`\");\n            }\n\n            extensionsBuilder.put(extensionName, extension);\n            log.info().attr(\"extension\", extensionName)\n                    .log(\"Successfully loaded extension\");\n        });\n\n        return new ProxyExtensions(extensionsBuilder.build());\n    }\n\n    private final Map<String, ProxyExtensionWithClassLoader> extensions;","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-proxy/src/main/java/org/apache/pulsar/proxy/extensions/ProxyExtensions.java#L58-L94","documentation":"Thrown during proxy extension startup when the extension's NAR bundle cannot be loaded into a classloader (ProxyExtensionsUtils.load throws IOException). The proxy wraps it in a RuntimeException and aborts loading that extension. It indicates the extension archive itself is broken or unreadable, not that the extension rejected its name.","triggerScenarios":"Calling ProxyExtensions.load(configuration) at proxy startup where an extension configured via proxyExtensionsDirectory fails to unpack/instantiate: missing or corrupted .nar file, unreadable narExtractionDirectory, or an IOException during NAR extraction.","commonSituations":"Wrong extensions directory configured; NAR file truncated by a failed download or partial deploy; disk full or no write permission on the NAR extraction directory; extension NAR built against an incompatible Pulsar version.","solutions":["Check the preceding 'Failed to load the extension' ERROR log line which carries the root IOException and fix the underlying cause","Verify the .nar file in the proxy extensions directory is complete and readable (re-download/redeploy it)","Ensure proxy narExtractionDirectory exists and is writable by the proxy process (check disk space and permissions)","Confirm the extension NAR version is compatible with your Pulsar proxy version, then restart the proxy"],"exampleFix":"// before\nproxyExtensionsDirectory=/opt/pulsar/extensions\nproxyExtensionNames=http\n// after: rebuild/copy a complete NAR and ensure the extraction dir is writable\nproxyExtensionsDirectory=/opt/pulsar/extensions\nproxyExtensionNames=http\n# ls -l /opt/pulsar/extensions/*.nar  # confirm file exists and is not 0 bytes\n# mkdir -p /tmp/pulsar-nar && chown pulsar:pulsar /tmp/pulsar-nar","handlingStrategy":"validation","validationCode":"// Before proxy start\nFile nar = new File(extDir, name + \".nar\");\nif (!nar.isFile() || nar.length() == 0) throw new IllegalStateException(\"Missing/empty NAR: \" + nar);\nFile extractDir = new File(conf.getNarExtractionDirectory());\nif (!extractDir.canWrite()) throw new IllegalStateException(\"NAR extraction dir not writable: \" + extractDir);","typeGuard":null,"tryCatchPattern":"try { proxyExtensions.load(conf); } catch (RuntimeException e) { log.error(\"Extension load failed: {}\", e.getMessage(), e); System.exit(1); }","preventionTips":["Checksum-verify NAR artifacts after download/deploy","Pre-create the NAR extraction directory with correct ownership","Keep extension NAR versions aligned with the Pulsar proxy version"],"tags":["pulsar-proxy","extensions","nar-loading","startup"],"backgroundTag":"nar-extension-load-failed","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}