testcontainers/testcontainers-java · error · RuntimeException

This container's image does not have a healthcheck…

Error message

This container's image does not have a healthcheck declared, so health cannot be determined. Either amend the image or use another approach to determine whether containers are healthy.

What it means

ContainerState.isHealthy() inspects the container's Docker health state; if the image declares no HEALTHCHECK the Docker API returns no health object and the method throws a RuntimeException, since healthiness is undefined without a healthcheck.

Solutions

1. Add a HEALTHCHECK instruction to the image Dockerfile and rebuild
2. Use a different wait strategy, e.g. Wait.forListeningPort() or Wait.forHttp("/health") instead of forHealthcheck()
3. If the base image can't be changed, wrap the container in a new image that adds the HEALTHCHECK

Example fix

// before
new GenericContainer<>("nginx:1.25").waitingFor(Wait.forHealthcheck());
// after
new GenericContainer<>("nginx:1.25").waitingFor(Wait.forHttp("/").forStatusCode(200));

boolean hasHealthcheck = DockerClientFactory.instance().client().inspectImageCmd(image).exec().getConfig().getHealthcheck() != null; if (!hasHealthcheck) useFallbackWaitStrategy();

try { return container.isHealthy(); } catch (RuntimeException e) { if (e.getMessage().contains("healthcheck declared")) { return fallbackReadinessCheck(container); } throw e; }

When it happens

Trigger: Calling isHealthy(), or using Wait.forHealthcheck() / waitingFor(HealthCheckWaitStrategy), on a container whose image has no HEALTHCHECK instruction.

Common situations: Using Healthcheck-based wait strategies with community images that lack HEALTHCHECK; expecting Docker's health status for custom Dockerfiles without a HEALTHCHECK line.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Timed out waiting for container to become healthy
• An exception while executing the internal check
• Services named do not exist, but wait conditions have been…
• Requested port ( ) is not mapped
• Wait strategy failed. Container is removed

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

Appendix: source

Thrown at core/src/main/java/org/testcontainers/containers/ContainerState.java:111

            return "created".equalsIgnoreCase(status) || isRunning();
        } catch (DockerException e) {
            return false;
        }
    }

    /**
     * @return has the container health state 'healthy'?
     */
    default boolean isHealthy() {
        if (getContainerId() == null) {
            return false;
        }

        try {
            InspectContainerResponse inspectContainerResponse = getCurrentContainerInfo();
            HealthState health = inspectContainerResponse.getState().getHealth();
            if (health == null) {
                throw new RuntimeException(
                    "This container's image does not have a healthcheck declared, so health cannot be determined. Either amend the image or use another approach to determine whether containers are healthy."
                );
            }

            return STATE_HEALTHY.equals(health.getStatus());
        } catch (DockerException e) {
            return false;
        }
    }

    /**
     * Inspects the container and returns up-to-date inspection response.
     *
     * @return up-to-date container inspect response
     * @see #getContainerInfo()
     */
    default InspectContainerResponse getCurrentContainerInfo() {
        return getDockerClient().inspectContainerCmd(getContainerId()).exec();

View on GitHub (pinned to 8e549514e3)