{"record":{"id":"12f40254222570bc","repo":"apache/pulsar","slug":"protocol-handler-name-does-not-provide-a-prot","errorCode":null,"errorMessage":"Protocol handler `${name}` does NOT provide a protocol handler implementation","messagePattern":"Protocol handler `(.+?)` does NOT provide a protocol handler implementation","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"pulsar-broker/src/main/java/org/apache/pulsar/broker/protocol/ProtocolHandlerUtils.java","lineNumber":132,"sourceCode":"    /**\n     * Load the protocol handler according to the handler definition.\n     *\n     * @param metadata the protocol handler definition.\n     * @return\n     */\n    @SuppressWarnings(\"unchecked\")\n    static ProtocolHandlerWithClassLoader load(ProtocolHandlerMetadata metadata,\n                                               String narExtractionDirectory) throws IOException {\n        final File narFile = metadata.getArchivePath().toAbsolutePath().normalize().toFile();\n        NarClassLoader ncl = NarClassLoaderBuilder.builder()\n                .narFile(narFile)\n                .parentClassLoader(ProtocolHandler.class.getClassLoader())\n                .extractionDirectory(narExtractionDirectory)\n                .build();\n\n        ProtocolHandlerDefinition phDef = getProtocolHandlerDefinition(ncl);\n        if (StringUtils.isBlank(phDef.getHandlerClass())) {\n            throw new IOException(\"Protocol handler `\" + phDef.getName() + \"` does NOT provide a protocol\"\n                + \" handler implementation\");\n        }\n\n        try {\n            Class handlerClass = ncl.loadClass(phDef.getHandlerClass());\n            Object handler = handlerClass.getDeclaredConstructor().newInstance();\n            if (!(handler instanceof ProtocolHandler)) {\n                throw new IOException(\"Class \" + phDef.getHandlerClass()\n                    + \" does not implement protocol handler interface\");\n            }\n            ProtocolHandler ph = (ProtocolHandler) handler;\n            return new ProtocolHandlerWithClassLoader(ph, ncl);\n        } catch (Throwable t) {\n            rethrowIOException(t);\n            return null;\n        }\n    }\n","sourceCodeStart":114,"sourceCodeEnd":150,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-broker/src/main/java/org/apache/pulsar/broker/protocol/ProtocolHandlerUtils.java#L114-L150","documentation":"Thrown by ProtocolHandlerUtils.load when a NAR protocol-handler bundle is loaded but its ProtocolHandlerDefinition has no 'handlerClass' configured. The broker cannot instantiate anything because the NAR metadata does not point to a class that implements the ProtocolHandler interface.","triggerScenarios":"Calling ProtocolHandlerUtils.load(definition, narExtractionDirectory) with a protocol handler NAR whose META-INF ProtocolHandlerDefinition defines a name but no handlerClass property.","commonSituations":"Hand-built or mispackaged protocol handler NARs; a hand-edited or generated metadata file missing the handler-class entry; building a NAR with the Pulsar NAR plugin but forgetting to declare the implementation class.","solutions":["Fix the handler NAR's ProtocolHandlerDefinition metadata so it declares the handler class (e.g. handlerClass=org.example.MyProtocolHandler) and rebuild the NAR.","Verify with `unzip -p your-handler.nar META-INF/... | grep handlerClass` that the definition includes the class name before deploying to protocols/.","Use the official pulsar-proxy / pulsar-metering NAR maven plugin configuration so the definition is generated correctly.","Re-download/reinstall the NAR from a trusted distribution; the copy in the protocols/ directory may be corrupt or truncated."],"exampleFix":"// before (NAR metadata missing class)\n{\n  \"name\": \"kafka\",\n  \"description\": \"kafka on pulsar\"\n}\n// after\n{\n  \"name\": \"kafka\",\n  \"description\": \"kafka on pulsar\",\n  \"handlerClass\": \"org.apache.pulsar.protocol.KafkaProtocolHandler\"\n}","handlingStrategy":"validation","validationCode":"// Pre-deploy check of the NAR metadata\njava.util.jar.JarFile nar = new java.util.jar.JarFile(narPath);\njava.util.jar.Attributes attrs = nar.getManifest().getMainAttributes();\nString handlerClass = attrs.getValue(\"Pulsar-ProtocolHandler\"); // or parse META-INF/yaml definition\nif (handlerClass == null || handlerClass.isBlank())\n  throw new IllegalStateException(\"NAR \" + narPath + \" declares no handlerClass\");","typeGuard":null,"tryCatchPattern":"try {\n  handlers = ProtocolHandlers.load(conf);\n} catch (RuntimeException e) {\n  if (e.getMessage() != null && e.getMessage().contains(\"does NOT provide a protocol\")) {\n    log.error(\"Handler NAR missing handlerClass; fix metadata and redeploy\");\n  }\n  throw e;\n}","preventionTips":["Always declare handlerClass in the NAR's ProtocolHandlerDefinition","Validate NAR metadata in CI before publishing the artifact","Use the official NAR maven plugin so the definition is generated","Unzip and inspect a freshly built NAR before deployment"],"tags":["broker","protocol-handler","configuration","nar"],"backgroundTag":"missing-implementation-class","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"}