testcontainers/testcontainers-java · error · IllegalArgumentException

extension version must not be null or empty

Error message

extension version must not be null or empty

What it means

Builder validation in HiveMQExtension.build: after checking the extension id, it validates that the extension name is non-null and non-empty, otherwise IllegalArgumentException is thrown. The at-fault input is a builder whose name was never set or set to an empty string.

Solutions

1. Call .version("1.0.0") with a concrete version string before build()
2. Ensure your build tool injects the project version into the builder call
3. Assert all required builder fields (id, name, version, mainClass) are populated in tests

Example fix

// before
builder.id("ext").name("my-extension").build();
// after
builder.id("ext").name("my-extension").version("1.0.0").build();

if (version == null || version.isEmpty()) throw new IllegalStateException("Set builder.version() before build()");

boolean hasVersion = version != null && !version.isBlank();

When it happens

Trigger: Calling build() without version(...), or version(null)/version("").

Common situations: Generating the extension descriptor from build metadata where the project version is not yet resolved (e.g. missing version in Gradle/Maven config); template code with version left blank.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• extension main class must not be null
• extension name 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/6a157b432b197ab3. Report an issue: GitHub.

Appendix: source

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

        @Nullable
        private Class<?> mainClass;

        @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}.

View on GitHub (pinned to 8e549514e3)