{"record":{"id":"6680ff88d1ba0b6b","repo":"apache/pulsar","slug":"wraps-classnotfoundexception-for-brokerentrymetad","errorCode":null,"errorMessage":"(wraps ClassNotFoundException for BrokerEntryMetadataInterceptor)","messagePattern":"\\(wraps ClassNotFoundException for BrokerEntryMetadataInterceptor\\)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"pulsar-common/src/main/java/org/apache/pulsar/common/intercept/BrokerEntryMetadataUtils.java","lineNumber":58,"sourceCode":"                    @SuppressWarnings(\"unchecked\") // class is loaded by name and expected to implement the interface\n                    Class<BrokerEntryMetadataInterceptor> clz = (Class<BrokerEntryMetadataInterceptor>) ClassLoaderUtils\n                            .loadClass(interceptorName, classLoader);\n                    try {\n                        interceptors.add(clz.getDeclaredConstructor().newInstance());\n                    } catch (InstantiationException | IllegalAccessException\n                            | InvocationTargetException | NoSuchMethodException e) {\n                        log.error()\n                                .attr(\"interceptorName\", interceptorName)\n                                .exception(e)\n                                .log(\"Create new BrokerEntryMetadataInterceptor instance failed.\");\n                        throw new RuntimeException(e);\n                    }\n                } catch (ClassNotFoundException e) {\n                    log.error()\n                            .attr(\"interceptorName\", interceptorName)\n                            .exception(e)\n                            .log(\"Load BrokerEntryMetadataInterceptor class failed.\");\n                    throw new RuntimeException(e);\n                }\n            }\n        }\n        return interceptors;\n    }\n    public static <T> Set<T> loadInterceptors(\n            Set<String> interceptorNames, ClassLoader classLoader) {\n        Set<T> interceptors = new LinkedHashSet<>();\n        if (interceptorNames != null && interceptorNames.size() > 0) {\n            for (String interceptorName : interceptorNames) {\n                try {\n                    @SuppressWarnings(\"unchecked\") // class is loaded by name and expected to match type T\n                    Class<T> clz = (Class<T>) ClassLoaderUtils\n                        .loadClass(interceptorName, classLoader);\n                    try {\n                        interceptors.add(clz.getDeclaredConstructor().newInstance());\n                    } catch (InstantiationException | IllegalAccessException\n                        | InvocationTargetException | NoSuchMethodException e) {","sourceCodeStart":40,"sourceCodeEnd":76,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-common/src/main/java/org/apache/pulsar/common/intercept/BrokerEntryMetadataUtils.java#L40-L76","documentation":"In loadBrokerEntryMetadataInterceptors, if the interceptor class named in configuration cannot be found on the classpath, ClassNotFoundException is logged and wrapped in a RuntimeException and broker startup/usage fails.","triggerScenarios":"brokerEntryMetadataInterceptors contains a fully-qualified class name that is not present on the broker's classpath (misspelled name, missing jar, wrong package).","commonSituations":"Custom interceptor plugin jar not copied to the broker's lib directory, class renamed in an upgrade, fat-fingered config value in broker.conf.","solutions":["Correct the class name in brokerEntryMetadataInterceptors to match the actual fully-qualified class","Install the jar containing the interceptor into the broker classpath (e.g. lib/ or plugins directory)","Confirm with the broker log line 'Load BrokerEntryMetadataInterceptor class failed.' which name failed"],"exampleFix":"// before\nbrokerEntryMetadataInterceptors=org.example.MyEntryMetaInterceptor // jar missing\n// after\nbrokerEntryMetadataInterceptors=org.example.entrymeta.MyEntryMetaInterceptor // corrected FQCN, jar installed","handlingStrategy":"validation","validationCode":"try {\n    Class.forName(configuredInterceptorName);\n} catch (ClassNotFoundException e) {\n    throw new IllegalStateException(\"Interceptor class not on broker classpath: \" + configuredInterceptorName);\n}","typeGuard":null,"tryCatchPattern":"try {\n    interceptors = BrokerEntryMetadataUtils.loadBrokerEntryMetadataInterceptors(names, conf);\n} catch (RuntimeException e) {\n    if (e.getCause() instanceof ClassNotFoundException) {\n        throw new IllegalStateException(\"Install the jar containing \" + e.getCause().getMessage(), e);\n    }\n    throw e;\n}","preventionTips":["Use fully-qualified class names copied from the interceptor source, not hand-typed","Deploy plugin jars to every broker in the cluster, not just one","Verify classpath contents after broker upgrades (class renames happen)"],"tags":["classpath","broker-entry-metadata","configuration","reflection"],"backgroundTag":"class-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"}