{"record":{"id":"02c3c88f5363d6bf","repo":"apache/pulsar","slug":"no-protocol-handler-is-found-for-protocol-proto","errorCode":null,"errorMessage":"No protocol handler is found for protocol `${protocol}`. Available protocols are : ${handlers}","messagePattern":"No protocol handler is found for protocol `(.+?)`\\. Available protocols are : (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"pulsar-broker/src/main/java/org/apache/pulsar/broker/protocol/ProtocolHandlers.java","lineNumber":68,"sourceCode":"     *\n     * @param conf the pulsar broker service configuration\n     * @return the collection of protocol handlers\n     */\n    public static ProtocolHandlers load(ServiceConfiguration conf) throws IOException {\n        if (conf.getMessagingProtocols().isEmpty()) {\n            return new ProtocolHandlers(Collections.emptyMap());\n        }\n        ProtocolHandlerDefinitions definitions =\n                ProtocolHandlerUtils.searchForHandlers(\n                        conf.getProtocolHandlerDirectory(), conf.getNarExtractionDirectory());\n\n        ImmutableMap.Builder<String, ProtocolHandlerWithClassLoader> handlersBuilder = ImmutableMap.builder();\n\n        conf.getMessagingProtocols().forEach(protocol -> {\n\n            ProtocolHandlerMetadata definition = definitions.handlers().get(protocol);\n            if (null == definition) {\n                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 + \"`\");","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-broker/src/main/java/org/apache/pulsar/broker/protocol/ProtocolHandlers.java#L50-L86","documentation":"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.","triggerScenarios":"Broker startup with messagingProtocols containing a protocol key that has no matching NAR in the protocols/ directory (definitions.handlers().get(protocol) returns null).","commonSituations":"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.","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."],"exampleFix":"// before (broker.conf)\nmessagingProtocols=kopa\n// after\nmessagingProtocols=kafka","handlingStrategy":"validation","validationCode":"// Before startup: confirm every configured protocol has a NAR in protocols/\njava.io.File dir = new java.io.File(conf.getProtocolsDirectory() != null ? conf.getProtocolsDirectory() : \"protocols\");\nfor (String p : conf.getMessagingProtocols().split(\",\")) {\n  boolean found = dir.listFiles((d, n) -> n.endsWith(\".nar\")) != null;\n  if (!found) throw new IllegalStateException(\"No NAR deployed for protocol: \" + p);\n}","typeGuard":null,"tryCatchPattern":"try {\n  handlers = ProtocolHandlers.load(conf);\n} catch (RuntimeException e) {\n  if (e.getMessage() != null && e.getMessage().startsWith(\"No protocol handler is found for protocol\")) {\n    log.error(\"Check messagingProtocols vs deployed NAR names; available: see broker log\");\n  }\n  throw e;\n}","preventionTips":["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"],"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-14T05:17:10.506Z"}