apache/pulsar · critical · RuntimeException

Malformed protocol handler found for protocol `${protocol}`

Error message

Malformed protocol handler found for protocol `${protocol}`

What it means

Thrown by ProtocolHandlers.load when a loaded handler's accept(protocol) returns false, meaning the handler itself rejects the protocol name it was registered under. The broker closes the handler and aborts startup because the mapping between config and handler is inconsistent.

Source

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

                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 + "`");
            }

            handlersBuilder.put(protocol, handler);
            log.info().attr("protocol", protocol).log("Successfully loaded protocol handler for protocol ``");
        });

        return new ProtocolHandlers(handlersBuilder.build());
    }

    private final Map<String, ProtocolHandlerWithClassLoader> handlers;

    ProtocolHandlers(Map<String, ProtocolHandlerWithClassLoader> handlers) {
        this.handlers = handlers;
    }

    /**
     * Return the handler for the provided <tt>protocol</tt>.
     *

View on GitHub (pinned to 820761864e)

Solutions

Align messagingProtocols with the protocol names the handler's accept() method supports (check the handler's docs/source).
Use a matching version of the handler NAR built for your broker version.
Check how the handler parses protocol names (some accept comma-separated variants) and use one of the supported strings.
If you wrote the handler, update accept() to return true for the configured protocol name.

Example fix

// before
messagingProtocols=kafkaConnect
// after (name the handler accepts)
messagingProtocols=kafka

Defensive patterns

Strategy: validation

Validate before calling

// Only configure protocol names documented as accepted by the handler
// e.g. KafkaProtocolHandler.accept() supports: kafka, kop
java.util.Set<String> accepted = java.util.Set.of("kafka", "kop");
for (String p : conf.getMessagingProtocols().split(",")) {
  if (!accepted.contains(p.trim()))
    throw new IllegalStateException("Handler will reject protocol name: " + p);
}

Try / catch

try {
  handlers = ProtocolHandlers.load(conf);
} catch (RuntimeException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Malformed protocol handler found")) {
    log.error("Handler rejected its configured protocol name via accept(); align names");
  }
  throw e;
}

Prevention

Read the handler's accept() implementation/docs to learn valid names
Use the canonical protocol name from the NAR documentation
Keep handler NAR version in sync with broker version
Test protocol loading in a staging broker before production

When it happens

Trigger: After a successful ProtocolHandlerUtils.load, handler.accept(protocol) is false — the NAR's declared handler does not recognize the protocol key configured in messagingProtocols.

Common situations: Configuring a protocol alias the handler does not accept; mismatch between the definition name and the names the handler's accept() supports; mixing handler NAR versions where accept logic changed.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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