testcontainers/testcontainers-java · error · IllegalStateException

This container does not support reuse

Error message

This container does not support reuse

What it means

Thrown when container reuse is enabled (withReuse(true) or testcontainers.reuse.enable=true) but the specific container subclass reports via canBeReused() that it cannot be reused. Reuse requires the container to be deterministic and stateless enough; containers that configure things incompatible with reuse (e.g. mounted files that change, random ports, one-off commands) refuse it.

Solutions

1. Remove .withReuse(true) from this container or disable reuse in testcontainers.properties if the container type doesn't support it.
2. Override canBeReused() to return true in your custom container subclass only if it's safe (deterministic config, no session state).
3. Use manual labels/fixed names plus Ryuk suppression as an alternative caching strategy.
4. Ensure copied/mounted files are deterministic so reuse hashing is stable.

Example fix

// before
container.withReuse(true).start(); // IllegalStateException for this type
// after
// drop reuse for this container type:
container.start();

if (Boolean.parseBoolean(System.getProperty("testcontainers.reuse.enable"))
        && !containerSupportsReuse(container)) {
    // start without reuse instead of failing
}

null

try {
    container.withReuse(true).start();
} catch (IllegalStateException e) {
    if (e.getMessage().contains("does not support reuse")) {
        container.start(); // fallback: no reuse
    } else throw e;
}

When it happens

Trigger: Calling container.withReuse(true).start() on a container whose canBeReused() returns false — for example a GenericContainer with custom entrypoint/command, a DockerComposeContainer-like setup, or containers relying on session-scoped state; also when reuse is enabled globally in ~/.testcontainers.properties but the container class doesn't support it.

Common situations: Developers enabling .withReuse(true) hoping to speed up tests, without realizing some container types (e.g. those built from an image with a random name or with copy-to-container of changing files) opt out; upgrading Testcontainers and previously-reusable containers now throwing.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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

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

Appendix: source

Thrown at core/src/main/java/org/testcontainers/containers/GenericContainer.java:384

    }

    private void tryStart() {
        try {
            String dockerImageName = getDockerImageName();
            logger().debug("Starting container: {}", dockerImageName);

            Instant startedAt = Instant.now();
            logger().info("Creating container for image: {}", dockerImageName);
            CreateContainerCmd createCommand = dockerClient.createContainerCmd(dockerImageName);
            applyConfiguration(createCommand);

            createCommand.getLabels().putAll(DockerClientFactory.DEFAULT_LABELS);

            boolean reused = false;
            final boolean reusable;
            if (shouldBeReused) {
                if (!canBeReused()) {
                    throw new IllegalStateException("This container does not support reuse");
                }

                if (TestcontainersConfiguration.getInstance().environmentSupportsReuse()) {
                    createCommand
                        .getLabels()
                        .put(COPIED_FILES_HASH_LABEL, Long.toHexString(hashCopiedFiles().getValue()));

                    String hash = hash(createCommand);

                    containerId = findContainerForReuse(hash).orElse(null);

                    if (containerId != null) {
                        logger().info("Reusing container with ID: {} and hash: {}", containerId, hash);
                        reused = true;
                    } else {
                        logger().debug("Can't find a reusable running container with hash: {}", hash);

                        createCommand.getLabels().put(HASH_LABEL, hash);

View on GitHub (pinned to 8e549514e3)