testcontainers/testcontainers-java · error · IllegalArgumentException

extension main class must not be null

Error message

extension main class must not be null

What it means

HiveMQExtension.Builder.build() validates that mainClass was set; unlike the other fields it must only be non-null. The mainClass is the ExtensionMain implementation HiveMQ will instantiate inside the container.

Solutions

1. Call .mainClass(MyExtensionMain.class) before build()
2. Ensure the class passed implements com.hivemq.extension.sdk.api.ExtensionMain
3. Check any builder helper/wrapper actually forwards the mainClass parameter

Example fix

// before
builder.id("ext").name("n").version("1.0").build();
// after
builder.id("ext").name("n").version("1.0").mainClass(MyExtensionMain.class).build();

if (mainClass == null) throw new IllegalStateException("mainClass is required: pass your ExtensionMain implementation");

boolean validMain = mainClass != null && com.hivemq.extension.sdk.api.ExtensionMain.class.isAssignableFrom(mainClass);

try { builder.build(); } catch (IllegalArgumentException e) { /* report which required field is missing */ }

When it happens

Trigger: Calling build() without ever calling mainClass(...) on the builder.

Common situations: Forgetting to wire the extension's entry-point class; refactoring that removed the mainClass() call; building a shared test extension helper where mainClass is a parameter that was passed as null.

Related errors

• extension name must not be null or empty
• extension version must not be null or empty
• Could not create DISABLED file
• Could not parse extension id from
• Extension disabling timed out after

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

Appendix: source

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

        @NotNull
        private final LinkedList<Class<?>> additionalClasses = new LinkedList<>();

        /**
         * Builds the {@link HiveMQExtension} with the provided values or default values.
         * @return the HiveMQ Extension
         */
        public @NotNull HiveMQExtension build() {
            if (id == null || id.isEmpty()) {
                throw new IllegalArgumentException("extension id must not be null or empty");
            }
            if (name == null || name.isEmpty()) {
                throw new IllegalArgumentException("extension name must not be null or empty");
            }
            if (version == null || version.isEmpty()) {
                throw new IllegalArgumentException("extension version must not be null or empty");
            }
            if (mainClass == null) {
                throw new IllegalArgumentException("extension main class must not be null");
            }
            return new HiveMQExtension(
                id,
                name,
                version,
                priority,
                startPriority,
                disabledOnStartup,
                mainClass,
                additionalClasses
            );
        }

        /**
         * Sets the identifier of the {@link HiveMQExtension}.
         *
         * @param id the identifier, must not be empty
         * @return the {@link Builder}

View on GitHub (pinned to 8e549514e3)