{"record":{"id":"d43110f8c86a5f79","repo":"apache/pulsar","slug":"malformed-protocol-handler-found-for-protocol-p","errorCode":null,"errorMessage":"Malformed protocol handler found for protocol `${protocol}`","messagePattern":"Malformed protocol handler found for protocol `(.+?)`","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"pulsar-broker/src/main/java/org/apache/pulsar/broker/protocol/ProtocolHandlers.java","lineNumber":86,"sourceCode":"                throw new RuntimeException(\"No protocol handler is found for protocol `\" + protocol\n                    + \"`. Available protocols are : \" + definitions.handlers());\n            }\n\n            ProtocolHandlerWithClassLoader handler;\n            try {\n                handler = ProtocolHandlerUtils.load(definition, conf.getNarExtractionDirectory());\n            } catch (IOException e) {\n                log.error()\n                        .attr(\"protocol\", protocol)\n                        .exception(e)\n                        .log(\"Failed to load the protocol handler for protocol ` `\");\n                throw new RuntimeException(\"Failed to load the protocol handler for protocol `\" + protocol + \"`\");\n            }\n\n            if (!handler.accept(protocol)) {\n                handler.close();\n                log.error().attr(\"protocol\", protocol).log(\"Malformed protocol handler found for protocol ` `\");\n                throw new RuntimeException(\"Malformed protocol handler found for protocol `\" + protocol + \"`\");\n            }\n\n            handlersBuilder.put(protocol, handler);\n            log.info().attr(\"protocol\", protocol).log(\"Successfully loaded protocol handler for protocol ``\");\n        });\n\n        return new ProtocolHandlers(handlersBuilder.build());\n    }\n\n    private final Map<String, ProtocolHandlerWithClassLoader> handlers;\n\n    ProtocolHandlers(Map<String, ProtocolHandlerWithClassLoader> handlers) {\n        this.handlers = handlers;\n    }\n\n    /**\n     * Return the handler for the provided <tt>protocol</tt>.\n     *","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-broker/src/main/java/org/apache/pulsar/broker/protocol/ProtocolHandlers.java#L68-L104","documentation":"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.","triggerScenarios":"After a successful ProtocolHandlerUtils.load, handler.accept(protocol) is false — the NAR's declared handler does not recognize the protocol key configured in messagingProtocols.","commonSituations":"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.","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."],"exampleFix":"// before\nmessagingProtocols=kafkaConnect\n// after (name the handler accepts)\nmessagingProtocols=kafka","handlingStrategy":"validation","validationCode":"// Only configure protocol names documented as accepted by the handler\n// e.g. KafkaProtocolHandler.accept() supports: kafka, kop\njava.util.Set<String> accepted = java.util.Set.of(\"kafka\", \"kop\");\nfor (String p : conf.getMessagingProtocols().split(\",\")) {\n  if (!accepted.contains(p.trim()))\n    throw new IllegalStateException(\"Handler will reject protocol name: \" + p);\n}","typeGuard":null,"tryCatchPattern":"try {\n  handlers = ProtocolHandlers.load(conf);\n} catch (RuntimeException e) {\n  if (e.getMessage() != null && e.getMessage().startsWith(\"Malformed protocol handler found\")) {\n    log.error(\"Handler rejected its configured protocol name via accept(); align names\");\n  }\n  throw e;\n}","preventionTips":["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"],"tags":["broker","startup","protocol-handler","configuration"],"backgroundTag":"protocol-handler-not-found","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}