testcontainers/testcontainers-java · error · IllegalStateException

The class 'com.hivemq.extension.sdk.api.ExtensionMain' was…

Error message

The class 'com.hivemq.extension.sdk.api.ExtensionMain' was not found in the classpath.

What it means

Builder.mainClass(Class) attempts to load com.hivemq.extension.sdk.api.ExtensionMain from the classpath; if the HiveMQ extension SDK API is not a dependency, a ClassNotFoundException is converted to this IllegalStateException, because extension validation is impossible without the SDK interface.

Solutions

Add com.hivemq:hivemq-extension-sdk-api as a compile/test dependency
Check dependency scope so the SDK is on the classpath where the builder is used
Run mvn dependency:tree / gradle dependencies to confirm the SDK artifact resolves

Example fix

// before
// no sdk dependency; builder.mainClass(...) throws IllegalStateException
// after (Maven)
<dependency><groupId>com.hivemq</groupId><artifactId>hivemq-extension-sdk-api</artifactId><version>4.x</version><scope>test</scope></dependency>

Defensive patterns

Strategy: try-catch

Validate before calling

try { Class.forName("com.hivemq.extension.sdk.api.ExtensionMain"); } catch (ClassNotFoundException e) { throw new IllegalStateException("Add hivemq-extension-sdk-api dependency"); }

Try / catch

try { builder.mainClass(MyExt.class); } catch (IllegalStateException e) { if (e.getMessage().contains("not found in the classpath")) { /* add/fix hivemq-extension-sdk-api dependency */ } throw e; }

Prevention

Declare hivemq-extension-sdk-api explicitly next to the testcontainers hivemq module
Check the module's dependency tree in CI

When it happens

Trigger: Calling mainClass(...) while the hivemq-extension-sdk-api artifact is absent from the compile/test classpath.

Common situations: Adding the testcontainers hivemq module without adding the HiveMQ extension SDK dependency; scope misconfiguration (sdk only in another module); version change that removed a transitive sdk dependency.

Related errors

AI-assisted analysis of testcontainers/testcontainers-java@8e549514e3 (2026-09-12). Data as JSON: /api/errors/81e3c0841e8a78b0. Report an issue: GitHub.

Appendix: source

Thrown at modules/hivemq/src/main/java/org/testcontainers/hivemq/HiveMQExtension.java:312

         * This class MUST implement com.hivemq.extension.sdk.api.ExtensionMain.
         *
         * @param mainClass the main class
         * @return the {@link Builder}
         * @throws IllegalArgumentException if the provides class does not implement com.hivemq.extension.sdk.api.ExtensionMain}
         * @throws IllegalStateException if com.hivemq.extension.sdk.api.ExtensionMain is not found in the classpath
         */
        public @NotNull Builder mainClass(final @NotNull Class<?> mainClass) {
            try {
                final Class<?> extensionMain = Class.forName(EXTENSION_MAIN_CLASS_NAME);
                if (!extensionMain.isAssignableFrom(mainClass)) {
                    throw new IllegalArgumentException(
                        "The provided class does not implement '" + EXTENSION_MAIN_CLASS_NAME + "'"
                    );
                }
                this.mainClass = mainClass;
                return this;
            } catch (final ClassNotFoundException e) {
                throw new IllegalStateException(
                    "The class '" + EXTENSION_MAIN_CLASS_NAME + "' was not found in the classpath."
                );
            }
        }

        /**
         * Adds an additional class to the .jar file of the {@link HiveMQExtension}.
         *
         * @param clazz the additional class
         * @return the {@link Builder}
         */
        public @NotNull Builder addAdditionalClass(final @NotNull Class<?> clazz) {
            this.additionalClasses.add(clazz);
            return this;
        }
    }
}

View on GitHub (pinned to 8e549514e3)