apache/pulsar · error · RuntimeException

No extension is found for extension name `${extensionName}`.

Error message

No extension is found for extension name `${extensionName}`. Available extensions are : ${definitions.extensions()}

What it means

ProxyExtensions.load resolves each extension name from the proxyExtensions configuration against the set of NAR extension definitions discovered (via ServiceLoader from the extensions directory). If a configured name has no matching definition, a RuntimeException listing the available extensions is thrown at proxy startup. This is a fail-fast configuration validation: the proxy cannot enable an extension whose NAR is not installed.

Source

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

     *
     * @param conf the pulsar broker service configuration
     * @return the collection of extensions
     */
    public static ProxyExtensions load(ProxyConfiguration conf) throws IOException {
        if (conf.getProxyExtensions().isEmpty()) {
            return new ProxyExtensions(Collections.emptyMap());
        }
        ExtensionsDefinitions definitions =
                ProxyExtensionsUtils.searchForExtensions(
                        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 + "`");
            }

View on GitHub (pinned to 820761864e)

Solutions

1. Compare the configured name against the 'Available extensions' list in the message and fix the typo/case.
2. Install the extension NAR into the proxy extensions directory ($PULSAR_HOME/proxyextensions or conf proxyExtensionsDirectory) and restart.
3. Remove the unknown name from proxyExtensions in proxy.conf / proxyconfig if the extension is not needed.
4. Verify the NAR is valid and matches this Pulsar version (an unloadable NAR will not appear in definitions).

Example fix

# before (proxy.conf)
proxyExtensions=obfs4proxy
# after — name must match an installed NAR
proxyExtensions=authentication
# and ensure the NAR exists:
# cp pulsar-proxy-authentication.nar $PULSAR_HOME/proxyextensions/

java.io.File extDir = new java.io.File(conf.getProxyExtensionsDirectory());
Set<String> available = new HashSet<>();
for (java.io.File f : extDir.listFiles((d, n) -> n.endsWith(".nar"))) {
    available.add(f.getName().replaceFirst("\\.nar$", ""));
}
for (String ext : conf.getProxyExtensions()) {
    if (!available.stream().anyMatch(a -> a.contains(ext))) {
        throw new IllegalArgumentException("Extension " + ext + " not installed in " + extDir);
    }
}

try {
    proxyExtensions.load(conf);
} catch (RuntimeException e) {
    if (e.getMessage().startsWith("No extension is found")) {
        log.error("Fix proxyExtensions config or install the NAR: {}", e.getMessage());
    }
    throw e; // startup fails fast by design
}

When it happens

Trigger: Starting the Pulsar proxy with proxyExtensions set to a name not present in the extensions directory — e.g. typo'd name, NAR file missing from the extensions dir, wrong NAR deployed, or case mismatch.

Common situations: Operator copies config from a tutorial but never drops the extension NAR into $PULSAR_HOME/proxyextensions (or the configured extensionsDirectory); extension renamed between versions; extension NAR failed to load/parse so it is absent from definitions; deploying only to broker but enabling on proxy.

Related errors

• No offloader found for driver '${driverName}'. Please make s
• Could not open configuration file
• Malformed configuration file
• Need to specify a configuration file for broker
• Max message size need smaller than jvm directMemory

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