{"record":{"id":"ad5889af9b4489a4","repo":"apache/pulsar","slug":"wraps-classnotfoundexception-for-interceptor","errorCode":null,"errorMessage":"(wraps ClassNotFoundException for interceptor)","messagePattern":"\\(wraps ClassNotFoundException for interceptor\\)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"pulsar-common/src/main/java/org/apache/pulsar/common/intercept/BrokerEntryMetadataUtils.java","lineNumber":88,"sourceCode":"                    @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) {\n                        log.error()\n                            .attr(\"interceptorName\", interceptorName)\n                            .exception(e)\n                            .log(\"Create new 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 class failed.\");\n                    throw new RuntimeException(e);\n                }\n            }\n        }\n        return interceptors;\n    }\n}\n","sourceCodeStart":70,"sourceCodeEnd":95,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-common/src/main/java/org/apache/pulsar/common/intercept/BrokerEntryMetadataUtils.java#L70-L95","documentation":"In BrokerEntryMetadataUtils.loadInterceptors, a configured interceptor class name that cannot be resolved on the classpath raises ClassNotFoundException, which is logged and wrapped in a RuntimeException.","triggerScenarios":"Passing an interceptor name to loadInterceptors whose FQCN is misspelled, in the wrong package, or whose jar is not on the classpath.","commonSituations":"Missing plugin jar on broker/client classpath, class relocation after a version upgrade, configuration typos.","solutions":["Fix the interceptor class name in the configuration","Deploy the jar containing the interceptor to the classpath of the process loading it","Inspect the 'Load class failed.' log entry to confirm the exact missing name"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"for (String name : interceptorNames.split(\",\")) {\n    try {\n        Class.forName(name.trim(), false, loader);\n    } catch (ClassNotFoundException e) {\n        throw new IllegalStateException(\"Interceptor not found on classpath: \" + name.trim());\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    interceptors = BrokerEntryMetadataUtils.loadInterceptors(names, cl, Interceptor.class);\n} catch (RuntimeException e) {\n    if (e.getCause() instanceof ClassNotFoundException cnfe) {\n        throw new IllegalStateException(\"Missing interceptor class: \" + cnfe.getMessage(), e);\n    }\n    throw e;\n}","preventionTips":["Trim whitespace and validate names in config files before startup","Verify plugin jar placement (lib/ or configured plugin directory) after deployments","Document the FQCN of each shipped interceptor next to its jar"],"tags":["classpath","interceptor","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"}