testcontainers/testcontainers-java · warning

Unable to mount a file from test host into a running…

Error message

Unable to mount a file from test host into a running container. This may be a misconfiguration or limitation of your Docker environment. Some features might not work.

What it means

ContainerDef.applyTo() checks whether the Docker environment supports host file binds when the container definition has binds configured. If DockerClientFactory reports file mounting is unsupported (common in some remote/rootless setups), a WARN is emitted; container creation proceeds but bind-mounted features may silently not work.

Solutions

1. Ensure the Docker daemon runs locally or that paths exist identically on the daemon host
2. Verify shared-folder configuration for Docker Desktop / remote daemons
3. Disable the check via TestcontainersConfiguration isDisableChecks only if you know mounts work
4. Replace bind mounts with container copies (withCopyFileToContainer) if mounting is genuinely unsupported

Example fix

// before
container.withFileSystemBind("./config", "/etc/config", READ_WRITE);
// after
container.withCopyFileToContainer(MountableFile.forHostPath("./config"), "/etc/config");

// Probe mount support before relying on binds
boolean mountsOk = DockerClientFactory.instance().isFileMountingSupported();
if (!mountsOk) {
    // fall back to copy-based file transfer instead of bind mounts
    container.withCopyFileToContainer(MountableFile.forHostPath("./conf"), "/etc/conf");
}

When it happens

Trigger: Container definition contains bind mounts (copyToFileContainerPathMap/binds non-empty), checks are not disabled, and DockerClientFactory.instance().isFileMountingSupported() returns false — e.g. Docker inaccessible mount probing failed.

Common situations: Remote Docker daemons (DOCKER_HOST over TCP/ssh) where the daemon cannot see host paths; rootless Docker or podman setups; Windows/macOS VM-based Docker with misconfigured shared folders.

Related errors

• Could not obtain SSH_CONNECTION environment variable for…
• Previous attempts to find a Docker environment failed. Will…
• You should never close the global DockerClient!
• Check failed:
• Requested port ( ) is not mapped

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

Appendix: source

Thrown at core/src/main/java/org/testcontainers/containers/ContainerDef.java:118

        if (this.command != null) {
            createCommand.withCmd(this.command);
        }

        if (this.network != null) {
            hostConfig.withNetworkMode(this.network.getId());
            createCommand.withAliases(this.networkAliases.toArray(new String[0]));
        } else {
            if (this.networkMode != null) {
                createCommand.getHostConfig().withNetworkMode(this.networkMode);
            }
        }

        boolean shouldCheckFileMountingSupport =
            this.binds.size() > 0 && !TestcontainersConfiguration.getInstance().isDisableChecks();
        if (shouldCheckFileMountingSupport) {
            if (!DockerClientFactory.instance().isFileMountingSupported()) {
                log.warn(
                    "Unable to mount a file from test host into a running container. " +
                    "This may be a misconfiguration or limitation of your Docker environment. " +
                    "Some features might not work."
                );
            }
        }

        hostConfig.withBinds(this.binds.toArray(new Bind[0]));

        if (this.privilegedMode) {
            createCommand.getHostConfig().withPrivileged(this.privilegedMode);
        }

        Map<String, String> combinedLabels = new HashMap<>(this.labels);
        if (createCommand.getLabels() != null) {
            combinedLabels.putAll(createCommand.getLabels());
        }

View on GitHub (pinned to 8e549514e3)