{"record":{"id":"87fd1e478f737584","repo":"apache/pulsar","slug":"failed-to-load-the-protocol-handler-for-protocol","errorCode":null,"errorMessage":"Failed to load the protocol handler for protocol `${protocol}`","messagePattern":"Failed to load the protocol handler for protocol `(.+?)`","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"pulsar-broker/src/main/java/org/apache/pulsar/broker/protocol/ProtocolHandlers.java","lineNumber":80,"sourceCode":"        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 + \"`\");\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) {","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-broker/src/main/java/org/apache/pulsar/broker/protocol/ProtocolHandlers.java#L62-L98","documentation":"Thrown by ProtocolHandlers.load when ProtocolHandlerUtils.load throws an IOException (definition missing handler class, class not found, instantiation failure, etc.). The broker wraps the cause in a RuntimeException naming the protocol.","triggerScenarios":"Any failure in ProtocolHandlerUtils.load for a configured protocol: unreadable NAR, missing handlerClass (error 270), class load/instantiation errors, incompatible API during initialize.","commonSituations":"NAR compiled against a different Pulsar version causing NoSuchMethodError during load; corrupt NAR file in protocols/; JDK version mismatch; extraction directory not writable.","solutions":["Read the nested IOException cause in the log to identify the root failure (missing class, version mismatch, corrupt NAR).","Rebuild the NAR against the broker's Pulsar version and redeploy it to protocols/.","Confirm narExtractionDirectory is writable and has disk space so the NAR can be unpacked.","Run the broker with the JDK version required by the handler NAR."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Check the NAR is a valid zip and sized correctly before deployment\njava.util.zip.ZipFile z = null;\ntry { z = new java.util.zip.ZipFile(narPath); }\ncatch (java.io.IOException e) { throw new IllegalStateException(\"Corrupt NAR: \" + narPath, e); }\nfinally { if (z != null) z.close(); }","typeGuard":null,"tryCatchPattern":"try {\n  handlers = ProtocolHandlers.load(conf);\n} catch (RuntimeException e) {\n  if (e.getMessage() != null && e.getMessage().startsWith(\"Failed to load the protocol handler\")) {\n    Throwable root = e;\n    while (root.getCause() != null) root = root.getCause();\n    log.error(\"Handler load failed; root cause: \" + root); // NoClassDefFound/NoSuchMethod => version skew\n  }\n  throw e;\n}","preventionTips":["Build the NAR with provided-scope Pulsar dependencies to avoid API conflicts","Match NAR and broker Pulsar versions exactly","Verify NAR integrity (checksum) after transfer to the broker host","Ensure narExtractionDirectory is writable with free disk space","Run broker on the JDK version the NAR was built for"],"tags":["broker","startup","protocol-handler","classloader"],"backgroundTag":"protocol-handler-load-failed","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"}