{"record":{"id":"6af4d90019d71be4","repo":"apache/flink","slug":"the-class-is-not-a-subclass-of-as-is-req","errorCode":null,"errorMessage":"The class '{}' is not a subclass of '{}' as is required.","messagePattern":"The class '(.+?)' is not a subclass of '(.+?)' as is required\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"flink-core/src/main/java/org/apache/flink/util/InstantiationUtil.java","lineNumber":283,"sourceCode":"    /**\n     * Creates a new instance of the given class.\n     *\n     * @param <T> The generic type of the class.\n     * @param clazz The class to instantiate.\n     * @param castTo Optional parameter, specifying the class that the given class must be a\n     *     subclass off. This argument is added to prevent class cast exceptions occurring later.\n     * @return An instance of the given class.\n     * @throws RuntimeException Thrown, if the class could not be instantiated. The exception\n     *     contains a detailed message about the reason why the instantiation failed.\n     */\n    public static <T> T instantiate(Class<T> clazz, Class<? super T> castTo) {\n        if (clazz == null) {\n            throw new NullPointerException();\n        }\n\n        // check if the class is a subclass, if the check is required\n        if (castTo != null && !castTo.isAssignableFrom(clazz)) {\n            throw new RuntimeException(\n                    \"The class '\"\n                            + clazz.getName()\n                            + \"' is not a subclass of '\"\n                            + castTo.getName()\n                            + \"' as is required.\");\n        }\n\n        return instantiate(clazz);\n    }\n\n    /**\n     * Creates a new instance of the given class.\n     *\n     * @param <T> The generic type of the class.\n     * @param clazz The class to instantiate.\n     * @return An instance of the given class.\n     * @throws RuntimeException Thrown, if the class could not be instantiated. The exception\n     *     contains a detailed message about the reason why the instantiation failed.","sourceCodeStart":265,"sourceCodeEnd":301,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-core/src/main/java/org/apache/flink/util/InstantiationUtil.java#L265-L301","documentation":"InstantiationUtil.instantiate(clazz, castTo) checks castTo.isAssignableFrom(clazz) before calling newInstance and throws RuntimeException('The class X is not a subclass of Y as is required.') on mismatch. This is an explicit early type check so the failure is a clear message at instantiation time instead of a ClassCastException far away at first use.","triggerScenarios":"Passing a class that does not implement/extend the expected supertype — e.g. configuring a class named for interface A where the API requires subtype B, or two same-named classes from different loaders/packages after relocation.","commonSituations":"Plugin SPI-style loading where the configured implementation implements a different (or relocated duplicate) interface version; version upgrades that changed the required base type; copy-paste of a class name between incompatible extension points.","solutions":["Make the configured class implement/extend the exact required interface (same package and same classloader copy)","Eliminate duplicate copies of the interface jar (parent vs user classloader) so isAssignableFrom compares the same Class object","After shading/relocation, verify the interface FQCN in your implementation matches the one the framework loads"],"exampleFix":"// before\npublic class MySink implements SinkFunction<String> { ... } // API now requires Sink<String>\nInstantiationUtil.instantiate(clazz, Sink.class);\n// after\npublic class MySink implements org.apache.flink.api.connector.sink2.Sink<String> { ... }","handlingStrategy":"validation","validationCode":"if (!requiredType.isAssignableFrom(clazz)) {\n    throw new IllegalArgumentException(clazz + \" must implement \" + requiredType.getName());\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Compile plugin classes against the exact framework artifact version deployed","Remove duplicate copies of interface jars across loaders"],"tags":["reflection","classloader","api-mismatch"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}