testcontainers/testcontainers-java · critical · IllegalStateException

Check failed:

Error message

Check failed: 

What it means

DockerClientFactory.check() validates environment preconditions (e.g. docker version, disk space, mounts). When a check fails it logs a cross mark and throws IllegalStateException('Check failed: <message>') describing which precondition did not hold.

Solutions

1. Read the message suffix in the exception to see which check failed
2. Upgrade the Docker daemon to a version supported by this Testcontainers release
3. Fix the environment issue indicated (free disk space, fix storage driver, fix mount support)
4. Set the relevant testcontainers overrides if the check is a false positive

Info info = DockerClientFactory.instance().client().infoCmd().exec(); if (VersionComparator.compare(info.getServerVersion(), "1.30") < 0) { throw new SkipException("Docker too old: " + info.getServerVersion()); }

try { container.start(); } catch (IllegalStateException e) { if (e.getMessage().startsWith("Check failed:")) { Assumptions.assumeFalse(true, "Environment check failed: " + e.getMessage()); } throw e; }

When it happens

Trigger: Running inside DockerClientFactory.client()/getOrInitializeStrategy() during container startup when checkDockerVersion (or another private check such as checkDiskSpace or checkMountableFile) reports isSuccessful=false — e.g. a Docker daemon older than the minimum supported version.

Common situations: Old Docker daemon versions (pre-1.10-era APIs), Docker-in-CircleCI/CI runners with restricted storage drivers, out-of-disk environments failing the disk-space check.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• You should never close the global DockerClient!
• Requested port ( ) is not mapped
• execInContainer can only be used while the Container is…
• Container startup failed for image
• This container does not support reuse

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

Appendix: source

Thrown at core/src/main/java/org/testcontainers/DockerClientFactory.java:280

        } else {
            log.debug("Checks are disabled");
        }

        return client;
    }

    private void checkDockerVersion(String dockerVersion) {
        boolean versionIsSufficient = new ComparableVersion(dockerVersion).compareTo(new ComparableVersion("1.6.0")) >=
        0;
        check("Docker server version should be at least 1.6.0", versionIsSufficient);
    }

    private void check(String message, boolean isSuccessful) {
        if (isSuccessful) {
            log.info("\u2714\ufe0e {}", message);
        } else {
            log.error("\u274c {}", message);
            throw new IllegalStateException("Check failed: " + message);
        }
    }

    private boolean checkMountableFile() {
        DockerClient dockerClient = client();

        MountableFile mountableFile = MountableFile.forClasspathResource(
            ResourceReaper.class.getName().replace(".", "/") + ".class"
        );

        Volume volume = new Volume("/dummy");
        try {
            return runInsideDocker(
                createContainerCmd -> {
                    createContainerCmd.withBinds(new Bind(mountableFile.getResolvedPath(), volume, AccessMode.ro));
                },
                (__, containerId) -> {
                    try (

View on GitHub (pinned to 8e549514e3)