apache/pulsar · critical · RuntimeException

Failed to load the extension for extension name `${extension

Error message

Failed to load the extension for extension name `${extensionName}`

What it means

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.

Source

Thrown at pulsar-proxy/src/main/java/org/apache/pulsar/proxy/extensions/ProxyExtensions.java:76

                        conf.getProxyExtensionsDirectory(), conf.getNarExtractionDirectory());

        ImmutableMap.Builder<String, ProxyExtensionWithClassLoader> extensionsBuilder = ImmutableMap.builder();

        conf.getProxyExtensions().forEach(extensionName -> {

            ProxyExtensionMetadata definition = definitions.extensions().get(extensionName);
            if (null == definition) {
                throw new RuntimeException("No extension is found for extension name `" + extensionName
                    + "`. Available extensions are : " + definitions.extensions());
            }

            ProxyExtensionWithClassLoader extension;
            try {
                extension = ProxyExtensionsUtils.load(definition, conf.getNarExtractionDirectory());
            } catch (IOException e) {
                log.error().attr("extension", extensionName).exception(e)
                        .log("Failed to load the extension");
                throw new RuntimeException("Failed to load the extension for extension name `" + extensionName + "`");
            }

            if (!extension.accept(extensionName)) {
                extension.close();
                log.error().attr("extension", extensionName)
                        .log("Malformed extension found");
                throw new RuntimeException("Malformed extension found for extension name `" + extensionName + "`");
            }

            extensionsBuilder.put(extensionName, extension);
            log.info().attr("extension", extensionName)
                    .log("Successfully loaded extension");
        });

        return new ProxyExtensions(extensionsBuilder.build());
    }

    private final Map<String, ProxyExtensionWithClassLoader> extensions;

View on GitHub (pinned to 820761864e)

Solutions

1. Check the preceding 'Failed to load the extension' ERROR log line which carries the root IOException and fix the underlying cause
2. Verify the .nar file in the proxy extensions directory is complete and readable (re-download/redeploy it)
3. Ensure proxy narExtractionDirectory exists and is writable by the proxy process (check disk space and permissions)
4. Confirm the extension NAR version is compatible with your Pulsar proxy version, then restart the proxy

Example fix

// before
proxyExtensionsDirectory=/opt/pulsar/extensions
proxyExtensionNames=http
// after: rebuild/copy a complete NAR and ensure the extraction dir is writable
proxyExtensionsDirectory=/opt/pulsar/extensions
proxyExtensionNames=http
# ls -l /opt/pulsar/extensions/*.nar  # confirm file exists and is not 0 bytes
# mkdir -p /tmp/pulsar-nar && chown pulsar:pulsar /tmp/pulsar-nar

// Before proxy start
File nar = new File(extDir, name + ".nar");
if (!nar.isFile() || nar.length() == 0) throw new IllegalStateException("Missing/empty NAR: " + nar);
File extractDir = new File(conf.getNarExtractionDirectory());
if (!extractDir.canWrite()) throw new IllegalStateException("NAR extraction dir not writable: " + extractDir);

try { proxyExtensions.load(conf); } catch (RuntimeException e) { log.error("Extension load failed: {}", e.getMessage(), e); System.exit(1); }

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Malformed extension found for extension name `${extensionNam
• extension for `${extensionName}` attempts to use ${address}
• extension `${name}` does NOT provide a protocol handler impl
• Class ${extensionClass} does not implement extension interfa
• Failed to start zookeeper :${e.getMessage()}

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/8600e0e2ae0db002. Report an issue: GitHub.