testcontainers/testcontainers-java · error · TimeoutException

Extension enabling timed out after

Error message

Extension enabling 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

enableExtension removes the DISABLED file in the extension's container directory and awaits a latch released by the HiveMQ control-center callback when the extension is enabled. If no acknowledgement arrives within the timeout, a TimeoutException is thrown. As with disabling, Community Edition images do not support this control-center mechanism (the message text reuses 'disabling' wording).

Solutions

1. Use a HiveMQ Enterprise Edition image that supports extension enable/disable.
2. Check container logs for extension startup errors after enabling.
3. Confirm the extension id is correct.
4. Increase the timeout Duration.

Example fix

// before
container.enableExtension("my-extension", Duration.ofSeconds(2)); // too short
// after
container.enableExtension("my-extension", Duration.ofSeconds(30));

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

try {
    container.enableExtension(extId, Duration.ofSeconds(30));
} catch (TimeoutException e) {
    throw new IllegalStateException("Extension enable not acknowledged — check container logs", e);
}

When it happens

Trigger: Calling container.enableExtension(extensionId, duration) where the broker never reports the extension enabled — Community Edition image, wrong extension id, extension failing to start after the DISABLED file is removed, or a too-short timeout.

Common situations: CE image without enterprise control center; extension fails at startup after enable (bad descriptor/config), so the callback never fires; container stopping concurrently; slow CI exceeding the default timeout.

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 disabling 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/effae85d02d093cd. Report an issue: GitHub.

Appendix: source

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

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

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

            execInContainer("rm", "-rf", containerPath);
            LOGGER.info("Removing DISABLED file in container path '{}'", containerPath);

            final boolean await = latch.await(timeout.getSeconds(), TimeUnit.SECONDS);
            if (!await) {
                throw new TimeoutException(
                    "Extension enabling 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);
        }
    }

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

View on GitHub (pinned to 8e549514e3)