What causes "extension id must not be null or empty" in testcontainers/testcontainers-java?

Add .id("your-extension-id") to the builder chain.

testcontainers/testcontainers-java · error · IllegalArgumentException

extension id must not be null or empty

Error message

extension id must not be null or empty

What it means

HiveMQExtension.Builder.build() validates that id, name, and version are all non-null and non-empty before constructing the HiveMQExtension. An absent or empty id fails first with this IllegalArgumentException. These fields are mandatory because they populate hivemq-extension.xml and the extension identity used by the broker.

Solutions

Add .id("your-extension-id") to the builder chain.
If the id comes from a variable, check it is non-null/non-empty before building.
Verify the builder chain actually targets the HiveMQExtension.Builder (a generic Builder import can hide the missing call).

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

if (extId == null || extId.isBlank()) throw new IllegalArgumentException("extension id must be provided");
// then: builder.id(extId)

Try / catch

try { ext = HiveMQExtension.builder()...build(); } catch (IllegalArgumentException e) { log.error("Invalid extension definition: {}", e.getMessage()); throw e; }

Prevention

Always set id, name, and version in the builder — all three are mandatory.
Load ids from constants, not optional env vars, in test fixtures.
Review builder chains after refactors to ensure no mandatory call was dropped.

When it happens

Trigger: Calling HiveMQExtension.builder()...build() without .id("...") or with id("") — e.g. id supplied from an empty variable/config.

Common situations: Copy-pasted builder omitting the id call; id read from an environment variable or system property that is unset; refactor renaming constants so the id call was dropped.

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

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

Appendix: source

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

        private int priority = 0;

        private int startPriority = 0;

        private boolean disabledOnStartup = false;

        @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,

View on GitHub (pinned to 8e549514e3)