{"record":{"id":"a0bfd944169d6be6","repo":"testcontainers/testcontainers-java","slug":"the-provided-class-does-not-implement-com-hivemq-extension","errorCode":null,"errorMessage":"The provided class does not implement 'com.hivemq.extension.sdk.api.ExtensionMain'","messagePattern":"The provided class does not implement 'com\\.hivemq\\.extension\\.sdk\\.api\\.ExtensionMain'","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/hivemq/src/main/java/org/testcontainers/hivemq/HiveMQExtension.java","lineNumber":305,"sourceCode":"        public @NotNull Builder disabledOnStartup(final boolean disabledOnStartup) {\n            this.disabledOnStartup = disabledOnStartup;\n            return this;\n        }\n\n        /**\n         * The main class of the {@link HiveMQExtension}.\n         * This class MUST implement com.hivemq.extension.sdk.api.ExtensionMain.\n         *\n         * @param mainClass the main class\n         * @return the {@link Builder}\n         * @throws IllegalArgumentException if the provides class does not implement com.hivemq.extension.sdk.api.ExtensionMain}\n         * @throws IllegalStateException if com.hivemq.extension.sdk.api.ExtensionMain is not found in the classpath\n         */\n        public @NotNull Builder mainClass(final @NotNull Class<?> mainClass) {\n            try {\n                final Class<?> extensionMain = Class.forName(EXTENSION_MAIN_CLASS_NAME);\n                if (!extensionMain.isAssignableFrom(mainClass)) {\n                    throw new IllegalArgumentException(\n                        \"The provided class does not implement '\" + EXTENSION_MAIN_CLASS_NAME + \"'\"\n                    );\n                }\n                this.mainClass = mainClass;\n                return this;\n            } catch (final ClassNotFoundException e) {\n                throw new IllegalStateException(\n                    \"The class '\" + EXTENSION_MAIN_CLASS_NAME + \"' was not found in the classpath.\"\n                );\n            }\n        }\n\n        /**\n         * Adds an additional class to the .jar file of the {@link HiveMQExtension}.\n         *\n         * @param clazz the additional class\n         * @return the {@link Builder}\n         */","sourceCodeStart":287,"sourceCodeEnd":323,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/modules/hivemq/src/main/java/org/testcontainers/hivemq/HiveMQExtension.java#L287-L323","documentation":"Builder.mainClass(Class) checks at runtime that the supplied class is assignable to com.hivemq.extension.sdk.api.ExtensionMain by loading the interface via Class.forName. If the provided class does not implement it, an IllegalArgumentException is thrown, because HiveMQ would fail to start the extension otherwise.","triggerScenarios":"Passing a Class<?> to mainClass(...) that does not implement ExtensionMain, e.g. a plain listener, helper, or wrong class picked up via reflection.","commonSituations":"Refactorings that renamed/moved the extension main class and an unrelated class got passed; dynamically resolving classes by name from config and grabbing the wrong one; generic test utility accepting arbitrary classes.","solutions":["Make the passed class implement com.hivemq.extension.sdk.api.ExtensionMain (implement void action(ExtensionContext))","Verify you are passing the extension entry-point class, not a helper/test class","Add a compile-time generic bound or check the class hierarchy before calling mainClass"],"exampleFix":"// before\nbuilder.mainClass(SomeHelper.class); // does not implement ExtensionMain\n// after\nbuilder.mainClass(MyExtensionMain.class); // class MyExtensionMain implements ExtensionMain","handlingStrategy":"validation","validationCode":"if (!com.hivemq.extension.sdk.api.ExtensionMain.class.isAssignableFrom(clazz)) throw new IllegalArgumentException(clazz + \" must implement ExtensionMain\");","typeGuard":"static boolean isExtensionMain(Class<?> c) { return com.hivemq.extension.sdk.api.ExtensionMain.class.isAssignableFrom(c); }","tryCatchPattern":"try { builder.mainClass(clazz); } catch (IllegalArgumentException e) { /* log wrong class and fall back to correct ExtensionMain impl */ }","preventionTips":["Type the builder call with the concrete ExtensionMain implementation class","Avoid passing Class<?> from reflection/config without an assignability check"],"tags":["hivemq","class-hierarchy","type-mismatch"],"backgroundTag":"type-mismatch","analyzedSha":"8e549514e3f01c57d70546fbb8599d138f3903e5","analyzedAt":"2026-09-12T14:56:41.227Z","contentChangedAt":"2026-09-12T14:56:41.227Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}