apache/pulsar · critical · RuntimeException

No protocol handler is found for protocol `${protocol}`. Ava

Error message

No protocol handler is found for protocol `${protocol}`. Available protocols are : ${handlers}

What it means

Thrown by ProtocolHandlers.load when a protocol named in broker.conf messagingProtocols has no corresponding loaded handler definition. The broker scanned protocols/ and the requested protocol name simply is not among the discovered handlers.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/protocol/ProtocolHandlers.java:68

     *
     * @param conf the pulsar broker service configuration
     * @return the collection of protocol handlers
     */
    public static ProtocolHandlers load(ServiceConfiguration conf) throws IOException {
        if (conf.getMessagingProtocols().isEmpty()) {
            return new ProtocolHandlers(Collections.emptyMap());
        }
        ProtocolHandlerDefinitions definitions =
                ProtocolHandlerUtils.searchForHandlers(
                        conf.getProtocolHandlerDirectory(), conf.getNarExtractionDirectory());

        ImmutableMap.Builder<String, ProtocolHandlerWithClassLoader> handlersBuilder = ImmutableMap.builder();

        conf.getMessagingProtocols().forEach(protocol -> {

            ProtocolHandlerMetadata definition = definitions.handlers().get(protocol);
            if (null == definition) {
                throw new RuntimeException("No protocol handler is found for protocol `" + protocol
                    + "`. Available protocols are : " + definitions.handlers());
            }

            ProtocolHandlerWithClassLoader handler;
            try {
                handler = ProtocolHandlerUtils.load(definition, conf.getNarExtractionDirectory());
            } catch (IOException e) {
                log.error()
                        .attr("protocol", protocol)
                        .exception(e)
                        .log("Failed to load the protocol handler for protocol ` `");
                throw new RuntimeException("Failed to load the protocol handler for protocol `" + protocol + "`");
            }

            if (!handler.accept(protocol)) {
                handler.close();
                log.error().attr("protocol", protocol).log("Malformed protocol handler found for protocol ` `");
                throw new RuntimeException("Malformed protocol handler found for protocol `" + protocol + "`");

View on GitHub (pinned to 820761864e)

Solutions

Make the protocol name in messagingProtocols exactly match the name declared inside the handler NAR's ProtocolHandlerDefinition.
Copy the handler NAR into the directory configured by narExtractionDirectory/protocols directory (default ./protocols) and restart.
Check the log line listing available protocols and correct the config accordingly.
Verify the NAR loads at all (fix any errors 270/271 first) so its name gets registered.

Example fix

// before (broker.conf)
messagingProtocols=kopa
// after
messagingProtocols=kafka

Defensive patterns

Strategy: validation

Validate before calling

// Before startup: confirm every configured protocol has a NAR in protocols/
java.io.File dir = new java.io.File(conf.getProtocolsDirectory() != null ? conf.getProtocolsDirectory() : "protocols");
for (String p : conf.getMessagingProtocols().split(",")) {
  boolean found = dir.listFiles((d, n) -> n.endsWith(".nar")) != null;
  if (!found) throw new IllegalStateException("No NAR deployed for protocol: " + p);
}

Try / catch

try {
  handlers = ProtocolHandlers.load(conf);
} catch (RuntimeException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("No protocol handler is found for protocol")) {
    log.error("Check messagingProtocols vs deployed NAR names; available: see broker log");
  }
  throw e;
}

Prevention

Keep messagingProtocols keys identical to the NAR definition names
Deploy NARs to the configured protocols directory before starting the broker
Copy the protocol name from the NAR docs, not from memory
Smoke-test broker startup in CI with the same NAR set

When it happens

Trigger: Broker startup with messagingProtocols containing a protocol key that has no matching NAR in the protocols/ directory (definitions.handlers().get(protocol) returns null).

Common situations: Typo in the messagingProtocols value (e.g. 'kopa' vs 'kafka'); NAR never copied to the protocols/ directory; NAR present but its internal definition name differs from the configured protocol key.

Related errors

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