testcontainers/testcontainers-java · error · ContainerLaunchException

Could not create DISABLED file

Error message

Could not create DISABLED file '${disabled.getAbsolutePath()}' on host machine.

What it means

HiveMQExtension.createExtension builds the extension directory on the host. When the extension is marked disabledOnStartup, it must create a DISABLED marker file inside that directory; if File.createNewFile() returns false (file already existed or creation failed), a ContainerLaunchException is thrown.

Solutions

1. Delete the stale extension directory (including DISABLED) before the test run.
2. Ensure the host directory is writable by the test process user.
3. Use a unique temp directory per test run to avoid collisions between parallel builds.
4. If reuse is intended, pre-create the DISABLED file yourself and avoid disabledOnStartup(true), or ignore the error.

Example fix

// before
// leftover /tmp/ext/DISABLED from previous run
HiveMQExtension.builder().disabledOnStartup(true)...build();
// after
FileUtils.deleteDirectory(new File("/tmp/ext"));
HiveMQExtension.builder().disabledOnStartup(true)...build();

File extDir = new File(tempDir, "my-extension");
if (extDir.exists()) FileUtils.deleteDirectory(extDir);
if (!extDir.mkdirs()) throw new IllegalStateException("Cannot create extension dir: " + extDir);

try { HiveMQExtension ext = builder.disabledOnStartup(true).build(); } catch (ContainerLaunchException e) { log.error("DISABLED file issue: {}", e.getMessage()); throw e; }

When it happens

Trigger: Calling HiveMQExtension.builder()...disabledOnStartup(true).build() and having the framework create the extension directory where a DISABLED file already exists (stale run leftovers) or the filesystem refuses the create (permissions, read-only dir).

Common situations: Reusing a persistent/temp directory across test runs where the previous DISABLED file was not cleaned; running tests as a user without write permission on the temp dir; parallel test executions sharing the same extension directory.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• Extension ' ' could not be mounted. It does not exist.
• Extension ' ' could not be mounted. It is not a directory.
• Extension disabling timed out after
• Extension enabling timed out after
• Could not parse extension id from

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

Appendix: source

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

        final File extensionDir = new File(tempDir, hiveMQExtension.getId());
        FileUtils.writeStringToFile(
            new File(extensionDir, "hivemq-extension.xml"),
            String.format(
                VALID_EXTENSION_XML,
                hiveMQExtension.getId(),
                hiveMQExtension.getName(),
                hiveMQExtension.getVersion(),
                hiveMQExtension.getPriority(),
                hiveMQExtension.getStartPriority()
            ),
            Charset.defaultCharset()
        );

        if (hiveMQExtension.isDisabledOnStartup()) {
            final File disabled = new File(extensionDir, "DISABLED");
            final boolean newFile = disabled.createNewFile();
            if (!newFile) {
                throw new ContainerLaunchException(
                    "Could not create DISABLED file '" + disabled.getAbsolutePath() + "' on host machine."
                );
            }
        }

        // Shadow Gradle plugin doesn't know how to handle ShrinkWrap's SPI definitions
        // This workaround creates the mappings programmatically
        // TODO write a custom Gradle Shadow transformer?
        ExtensionLoader extensionLoader = ShrinkWrap.getDefaultDomain().getConfiguration().getExtensionLoader();
        extensionLoader.addOverride(JavaArchive.class, JavaArchiveImpl.class);
        extensionLoader.addOverride(ZipExporter.class, ZipExporterImpl.class);

        final JavaArchive javaArchive = ShrinkWrap
            .create(JavaArchive.class)
            .addAsServiceProvider(EXTENSION_MAIN_CLASS_NAME, hiveMQExtension.getMainClass().getName());

        putSubclassesIntoJar(hiveMQExtension.getId(), hiveMQExtension.getMainClass(), javaArchive);
        for (final Class<?> additionalClass : hiveMQExtension.getAdditionalClasses()) {

View on GitHub (pinned to 8e549514e3)