\n * Must be called before the container is started.\n *
\n * The contents of the '/opt/hivemq/temp-extensions/' directory are copied to '/opt/hivemq/extensions/' before the container is started.\n *\n * @param mountableExtension the extension folder on the host machine\n * @return self\n */\n public @NotNull HiveMQContainer withExtension(final @NotNull MountableFile mountableExtension) {\n final File extensionDir = new File(mountableExtension.getResolvedPath());\n if (!extensionDir.exists()) {\n throw new ContainerLaunchException(\n \"Extension '\" + mountableExtension.getFilesystemPath() + \"' could not be mounted. It does not exist.\"\n );\n }\n if (!extensionDir.isDirectory()) {\n throw new ContainerLaunchException(\n \"Extension '\" +\n mountableExtension.getFilesystemPath() +\n \"' could not be mounted. It is not a directory.\"\n );\n }\n try {\n final String extensionDirName = getExtensionDirectoryName(extensionDir);\n final String containerPath = \"/opt/hivemq/temp-extensions/\" + extensionDirName;\n withCopyFileToContainer(cloneWithFileMode(mountableExtension), containerPath);\n LOGGER.info(\"Putting extension '{}' into '{}'\", extensionDirName, containerPath);\n } catch (final Exception e) {\n throw new ContainerLaunchException(e.getMessage() == null ? \"\" : e.getMessage(), e);\n }\n return self();\n }\n\n private @NotNull String getExtensionDirectoryName(final @NotNull File extensionDirectory) throws IOException {\n final File file = new File(extensionDirectory, \"hivemq-extension.xml\");","sourceCodeStart":233,"sourceCodeEnd":269,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/modules/hivemq/src/main/java/org/testcontainers/hivemq/HiveMQContainer.java#L233-L269","documentation":"After checking existence, the MountableFile-based withExtension validates that the resolved path is a directory, because HiveMQ extensions are mounted as folders under /opt/hivemq/temp-extensions/. Mounting a plain file would produce a broken extension, so the library throws this ContainerLaunchException.","triggerScenarios":"Passing a MountableFile that resolves to a regular file (e.g. a .zip or a single hivemq-extension.xml) instead of the extension's directory.","commonSituations":"Pointing at an archive or a single descriptor file instead of the unpacked extension folder; a symlink that resolves to a file; mixing up the extension jar path with the extension directory.","solutions":["Pass the extension directory (the folder containing hivemq-extension.xml), not a file inside it.","Unpack any zipped extension to a directory first, then wrap the directory with MountableFile.forHostPath(dir).","Check the resolved path with File.isDirectory() in a debugger/print to confirm what you are passing."],"exampleFix":"// before\nwithExtension(MountableFile.forHostPath(\"ext/my-extension.zip\")); // a file\n\n// after\nFile dir = unzipTo(new File(\"ext/my-extension.zip\"), tempDir);\nwithExtension(MountableFile.forHostPath(dir)); // directory containing hivemq-extension.xml","handlingStrategy":"validation","validationCode":"File dir = new File(mountableFile.getResolvedPath());\nif (!dir.isDirectory()) {\n throw new IllegalArgumentException(\"Expected an extension directory, got: \" + dir);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always pass the directory containing hivemq-extension.xml, never an archive or inner file.","Unzip extensions before mounting.","Name variables clearly (extensionDir vs extensionZip) to avoid mix-ups."],"tags":["testcontainers","hivemq","extension","not-a-directory"],"backgroundTag":"path-is-not-a-directory","analyzedSha":"8e549514e3f01c57d70546fbb8599d138f3903e5","analyzedAt":"2026-09-12T14:56:41.227Z","contentChangedAt":"2026-09-12T14:56:41.227Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}