apache/pulsar · error · RuntimeException

(wraps ClassNotFoundException for interceptor)

Error message

(wraps ClassNotFoundException for interceptor)

What it means

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.

Source

Thrown at pulsar-common/src/main/java/org/apache/pulsar/common/intercept/BrokerEntryMetadataUtils.java:88

                    @SuppressWarnings("unchecked") // class is loaded by name and expected to match type T
                    Class<T> clz = (Class<T>) ClassLoaderUtils
                        .loadClass(interceptorName, classLoader);
                    try {
                        interceptors.add(clz.getDeclaredConstructor().newInstance());
                    } catch (InstantiationException | IllegalAccessException
                        | InvocationTargetException | NoSuchMethodException e) {
                        log.error()
                            .attr("interceptorName", interceptorName)
                            .exception(e)
                            .log("Create new instance failed.");
                        throw new RuntimeException(e);
                    }
                } catch (ClassNotFoundException e) {
                    log.error()
                        .attr("interceptorName", interceptorName)
                        .exception(e)
                        .log("Load class failed.");
                    throw new RuntimeException(e);
                }
            }
        }
        return interceptors;
    }
}

View on GitHub (pinned to 820761864e)

Solutions

1. Fix the interceptor class name in the configuration
2. Deploy the jar containing the interceptor to the classpath of the process loading it
3. Inspect the 'Load class failed.' log entry to confirm the exact missing name

for (String name : interceptorNames.split(",")) {
    try {
        Class.forName(name.trim(), false, loader);
    } catch (ClassNotFoundException e) {
        throw new IllegalStateException("Interceptor not found on classpath: " + name.trim());
    }
}

try {
    interceptors = BrokerEntryMetadataUtils.loadInterceptors(names, cl, Interceptor.class);
} catch (RuntimeException e) {
    if (e.getCause() instanceof ClassNotFoundException cnfe) {
        throw new IllegalStateException("Missing interceptor class: " + cnfe.getMessage(), e);
    }
    throw e;
}

When it happens

Trigger: Passing an interceptor name to loadInterceptors whose FQCN is misspelled, in the wrong package, or whose jar is not on the classpath.

Common situations: Missing plugin jar on broker/client classpath, class relocation after a version upgrade, configuration typos.

Related errors

• (wraps ClassNotFoundException for BrokerEntryMetadataInterce
• (wraps reflective instantiation failure for interceptor)
• User class must be in class path
• Class must be in class path
• Failed to load an authorization provider.

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/ad5889af9b4489a4. Report an issue: GitHub.