What causes "Extension '{path}' could not be mounted. It does not exist." in testcontainers/testcontainers-java?

Build the extension before running the test (e.g. dependsOn the extension build task or run mvn install for the extension module).

testcontainers/testcontainers-java · error · ContainerLaunchException

Extension ' ' could not be mounted. It does not exist.

Error message

Extension '{path}' could not be mounted. It does not exist.

What it means

The MountableFile-based withExtension overload resolves the host path and validates it before mounting. If the resolved file/folder does not exist on disk, HiveMQContainer throws this ContainerLaunchException immediately rather than letting the container fail at copy time with a more obscure Docker error.

Solutions

Build the extension before running the test (e.g. dependsOn the extension build task or run mvn install for the extension module).
Verify the path with new File(path).exists() — print getResolvedPath() to see where it actually points.
Use MountableFile.forClasspathResource(...) for resources packaged with the test so the path always exists.

Example fix

// before
withExtension(MountableFile.forHostPath("target/my-extension")); // not built yet

// after
// build first (e.g. mvn -pl my-extension install), then:
File dir = new File("target/my-extension");
if (!dir.exists()) throw new IllegalStateException("Run 'mvn install' first");
withExtension(MountableFile.forHostPath(dir));

Defensive patterns

Strategy: validation

Validate before calling

File dir = new File(mountableExtension.getResolvedPath());
if (!dir.exists()) {
    throw new IllegalStateException("Extension path missing (build it first): " + dir.getAbsolutePath());
}

Prevention

Use MountableFile.forClasspathResource for packaged resources.
Ensure the extension build runs before tests (Gradle test.dependsOn buildExtension / Maven install).
Log getResolvedPath() when debugging path resolution.

When it happens

Trigger: Passing a MountableFile pointing to a host path that doesn't exist — e.g. forHostPath("target/hivemq-extension") built before the Maven/Gradle build produced it, a deleted build output, or a typo'd relative path resolved against the wrong working directory.

Common situations: Running the test before the extension module was built (mvn test without mvn install of the extension); CI checkout skipping a build step; paths that only exist after a code-gen step.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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

Appendix: source

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

        return self();
    }

    /**
     * Puts the given extension folder into '/opt/hivemq/temp-extensions/{directory-name}' inside the container.
     * It must at least contain a valid hivemq-extension.xml and a valid extension.jar in order to be executed.
     * The directory-name is taken from the id defined in the hivemq-extension.xml.
     * <p>
     * Must be called before the container is started.
     * <p>
     * The contents of the '/opt/hivemq/temp-extensions/' directory are copied to '/opt/hivemq/extensions/' before the container is started.
     *
     * @param mountableExtension the extension folder on the host machine
     * @return self
     */
    public @NotNull HiveMQContainer withExtension(final @NotNull MountableFile mountableExtension) {
        final File extensionDir = new File(mountableExtension.getResolvedPath());
        if (!extensionDir.exists()) {
            throw new ContainerLaunchException(
                "Extension '" + mountableExtension.getFilesystemPath() + "' could not be mounted. It does not exist."
            );
        }
        if (!extensionDir.isDirectory()) {
            throw new ContainerLaunchException(
                "Extension '" +
                mountableExtension.getFilesystemPath() +
                "' could not be mounted. It is not a directory."
            );
        }
        try {
            final String extensionDirName = getExtensionDirectoryName(extensionDir);
            final String containerPath = "/opt/hivemq/temp-extensions/" + extensionDirName;
            withCopyFileToContainer(cloneWithFileMode(mountableExtension), containerPath);
            LOGGER.info("Putting extension '{}' into '{}'", extensionDirName, containerPath);
        } catch (final Exception e) {
            throw new ContainerLaunchException(e.getMessage() == null ? "" : e.getMessage(), e);
        }

View on GitHub (pinned to 8e549514e3)