apache/pulsar · error · IOException

Protocol handler `${name}` does NOT provide a protocol handl

Error message

Protocol handler `${name}` does NOT provide a protocol handler implementation

What it means

Thrown by ProtocolHandlerUtils.load when a NAR protocol-handler bundle is loaded but its ProtocolHandlerDefinition has no 'handlerClass' configured. The broker cannot instantiate anything because the NAR metadata does not point to a class that implements the ProtocolHandler interface.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/protocol/ProtocolHandlerUtils.java:132

    /**
     * Load the protocol handler according to the handler definition.
     *
     * @param metadata the protocol handler definition.
     * @return
     */
    @SuppressWarnings("unchecked")
    static ProtocolHandlerWithClassLoader load(ProtocolHandlerMetadata metadata,
                                               String narExtractionDirectory) throws IOException {
        final File narFile = metadata.getArchivePath().toAbsolutePath().normalize().toFile();
        NarClassLoader ncl = NarClassLoaderBuilder.builder()
                .narFile(narFile)
                .parentClassLoader(ProtocolHandler.class.getClassLoader())
                .extractionDirectory(narExtractionDirectory)
                .build();

        ProtocolHandlerDefinition phDef = getProtocolHandlerDefinition(ncl);
        if (StringUtils.isBlank(phDef.getHandlerClass())) {
            throw new IOException("Protocol handler `" + phDef.getName() + "` does NOT provide a protocol"
                + " handler implementation");
        }

        try {
            Class handlerClass = ncl.loadClass(phDef.getHandlerClass());
            Object handler = handlerClass.getDeclaredConstructor().newInstance();
            if (!(handler instanceof ProtocolHandler)) {
                throw new IOException("Class " + phDef.getHandlerClass()
                    + " does not implement protocol handler interface");
            }
            ProtocolHandler ph = (ProtocolHandler) handler;
            return new ProtocolHandlerWithClassLoader(ph, ncl);
        } catch (Throwable t) {
            rethrowIOException(t);
            return null;
        }
    }

View on GitHub (pinned to 820761864e)

Solutions

1. Fix the handler NAR's ProtocolHandlerDefinition metadata so it declares the handler class (e.g. handlerClass=org.example.MyProtocolHandler) and rebuild the NAR.
2. Verify with `unzip -p your-handler.nar META-INF/... | grep handlerClass` that the definition includes the class name before deploying to protocols/.
3. Use the official pulsar-proxy / pulsar-metering NAR maven plugin configuration so the definition is generated correctly.
4. Re-download/reinstall the NAR from a trusted distribution; the copy in the protocols/ directory may be corrupt or truncated.

Example fix

// before (NAR metadata missing class)
{
  "name": "kafka",
  "description": "kafka on pulsar"
}
// after
{
  "name": "kafka",
  "description": "kafka on pulsar",
  "handlerClass": "org.apache.pulsar.protocol.KafkaProtocolHandler"
}

// Pre-deploy check of the NAR metadata
java.util.jar.JarFile nar = new java.util.jar.JarFile(narPath);
java.util.jar.Attributes attrs = nar.getManifest().getMainAttributes();
String handlerClass = attrs.getValue("Pulsar-ProtocolHandler"); // or parse META-INF/yaml definition
if (handlerClass == null || handlerClass.isBlank())
  throw new IllegalStateException("NAR " + narPath + " declares no handlerClass");

try {
  handlers = ProtocolHandlers.load(conf);
} catch (RuntimeException e) {
  if (e.getMessage() != null && e.getMessage().contains("does NOT provide a protocol")) {
    log.error("Handler NAR missing handlerClass; fix metadata and redeploy");
  }
  throw e;
}

When it happens

Trigger: Calling ProtocolHandlerUtils.load(definition, narExtractionDirectory) with a protocol handler NAR whose META-INF ProtocolHandlerDefinition defines a name but no handlerClass property.

Common situations: Hand-built or mispackaged protocol handler NARs; a hand-edited or generated metadata file missing the handler-class entry; building a NAR with the Pulsar NAR plugin but forgetting to declare the implementation class.

Related errors

• Class ${handlerClass} does not implement protocol handler in
• No protocol handler is found for protocol `${protocol}`. Ava
• Malformed protocol handler found for protocol `${protocol}`
• Protocol handler for `${handler}` attempts to use ${address}
• webServicePort/webServicePortTls or http/https bindAddresses

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