testcontainers/testcontainers-java · error · ContainerLaunchException

pathInHomeFolder must not be empty

Error message

pathInHomeFolder must not be empty

What it means

withFileInHomeFolder(MountableFile, String pathInHomeFolder) requires a non-blank relative path inside /opt/hivemq. If pathInHomeFolder is null-blank (only whitespace), a ContainerLaunchException is thrown, because the library cannot compute the container destination path.

Solutions

1. Pass a non-empty relative path such as "/extension/my-extension/extra.properties".
2. Validate/default the path variable before the call (e.g. Optional.ofNullable(path).filter(p->!p.isBlank()).orElse(defaultPath)).
3. If you meant to place a file in an extension folder, use withFileInExtensionHomeFolder(extensionId, file, path).

Example fix

// before
container.withFileInHomeFolder(file, "");
// after
container.withFileInHomeFolder(file, "/extension/my-extension/config.properties");

if (pathInHomeFolder == null || pathInHomeFolder.isBlank()) throw new IllegalArgumentException("pathInHomeFolder required");

try { container.withFileInHomeFolder(file, path); } catch (ContainerLaunchException e) { log.error("Bad home path: {}", e.getMessage()); throw e; }

When it happens

Trigger: Calling container.withFileInHomeFolder(mountableFile, " ") or withFileInHomeFolder(mountableFile, "") — or indirectly via withFileInExtensionHomeFolder with an empty path argument.

Common situations: Path value loaded from an empty config property or environment variable; variable interpolation failing and yielding empty string; caller confusing withFileInHomeFolder with a variant that takes no path.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• Service account token cannot be empty
• Elasticsearch CA certificate cannot be empty
• The number of replicas must be between 0 and 3 (inclusive)
• Bucket quota cannot be less than 100MB!
• The provided service (service) has no quota to configure

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

Appendix: source

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

    }

    /**
     * Puts the given file into the given subdirectory of the HiveMQ home folder '/opt/hivemq/{pathInHomeFolder}'.
     * <p>
     * Must be called before the container is started.
     *
     * @param mountableFile    the file on the host machine
     * @param pathInHomeFolder the path
     * @return self
     */
    public @NotNull HiveMQContainer withFileInHomeFolder(
        final @NotNull MountableFile mountableFile,
        final @NotNull String pathInHomeFolder
    ) {
        final File file = new File(mountableFile.getResolvedPath());

        if (pathInHomeFolder.trim().isEmpty()) {
            throw new ContainerLaunchException("pathInHomeFolder must not be empty");
        }

        if (!file.exists()) {
            throw new ContainerLaunchException("File '" + mountableFile.getFilesystemPath() + "' does not exist.");
        }
        final String containerPath = "/opt/hivemq" + PathUtil.prepareAppendPath(pathInHomeFolder);
        withCopyFileToContainer(cloneWithFileMode(mountableFile), containerPath);
        LOGGER.info("Putting file '{}' into container path '{}'.", file.getAbsolutePath(), containerPath);
        return self();
    }

    /**
     * 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 {timeOut}.
     * Note: Disabling Extensions is a HiveMQ Enterprise feature, it will not work when using the HiveMQ Community Edition.
     * <p>
     * This can only be called once the container is started.
     *

View on GitHub (pinned to 8e549514e3)