testcontainers/testcontainers-java · error · TimeoutException

Extension disabling timed out after

Error message

Extension disabling timed out after '${timeout.getSeconds()}' seconds. Maybe you are using a HiveMQ Community Edition image, which does not support disabling of extensions

What it means

disableExtension creates a DISABLED file in the extension's container directory and waits on a latch that is released when the HiveMQ control-center callback signals the extension was disabled. If the latch is not released within the given timeout, a TimeoutException is thrown, most commonly because the running image (HiveMQ Community Edition) does not support extension disabling via the control center.

Solutions

1. Use a HiveMQ Enterprise Edition image; Community Edition does not support disabling extensions.
2. Verify the extension id matches the id in hivemq-extension.xml.
3. Increase the timeout Duration (e.g. Duration.ofSeconds(30)) for slow environments.
4. Ensure the container and extension are fully started before calling disableExtension.

Example fix

// before
container.disableExtension("my-extension"); // CE image, always times out
// after
// use hivemq/hivemq4 enterprise image, then:
container.disableExtension("my-extension", Duration.ofSeconds(30));

boolean enterprise = container.getDockerImageName().contains("hivemq4") || System.getenv("HIVEMQ_LICENSE") != null;
if (!enterprise) throw new IllegalStateException("Extension disabling requires HiveMQ Enterprise Edition");

try {
    container.disableExtension(extId, Duration.ofSeconds(30));
} catch (TimeoutException e) {
    throw new IllegalStateException("Extension disable not acknowledged — check image edition and extension id", e);
}

When it happens

Trigger: Calling container.disableExtension(extensionId, duration) where the HiveMQ broker never acknowledges the disable — e.g. a Community Edition image, an extension that crashed on startup, a wrong extension id, or a container not yet fully started.

Common situations: Using hivemq/hivemq-ce (Community Edition) images that lack the enterprise control-center API; extension id typo; disable called before the extension finished enabling; timeout too short on a slow CI machine.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Extension enabling timed out after
• Extension ' ' could not be mounted. It does not exist.
• Extension ' ' could not be mounted. It is not a directory.
• Could not create DISABLED file
• Expiry time reached before end of output

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

Appendix: source

Thrown at modules/hivemq/src/main/java/org/testcontainers/hivemq/HiveMQContainer.java:451

    public void disableExtension(
        final @NotNull String extensionName,
        final @NotNull String extensionDirectory,
        final @NotNull Duration timeout
    ) throws TimeoutException {
        final String regEX = "(.*)Extension \"" + extensionName + "\" version (.*) stopped successfully(.*)";
        try {
            final String containerPath =
                "/opt/hivemq/extensions" + PathUtil.prepareInnerPath(extensionDirectory) + "DISABLED";

            final CountDownLatch latch = new CountDownLatch(1);
            containerOutputLatches.put(regEX, latch);

            execInContainer("touch", containerPath);
            LOGGER.info("Putting DISABLED file into container path '{}'", containerPath);

            final boolean await = latch.await(timeout.getSeconds(), TimeUnit.SECONDS);
            if (!await) {
                throw new TimeoutException(
                    "Extension disabling timed out after '" +
                    timeout.getSeconds() +
                    "' seconds. " +
                    "Maybe you are using a HiveMQ Community Edition image, " +
                    "which does not support disabling of extensions"
                );
            }
        } catch (final InterruptedException | IOException e) {
            throw new RuntimeException(e);
        } finally {
            containerOutputLatches.remove(regEX);
        }
    }

    /**
     * Disables the extension with the given name and extension directory name.
     * This method blocks until the HiveMQ log for successful disabling is consumed or it times out after 60 seconds.
     * Note: Disabling Extensions is a HiveMQ Enterprise feature, it will not work when using the HiveMQ Community Edition.

View on GitHub (pinned to 8e549514e3)