{"record":{"id":"3a422069950f8b85","repo":"testcontainers/testcontainers-java","slug":"this-container-does-not-support-reuse","errorCode":null,"errorMessage":"This container does not support reuse","messagePattern":"This container does not support reuse","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/testcontainers/containers/GenericContainer.java","lineNumber":384,"sourceCode":"    }\n\n    private void tryStart() {\n        try {\n            String dockerImageName = getDockerImageName();\n            logger().debug(\"Starting container: {}\", dockerImageName);\n\n            Instant startedAt = Instant.now();\n            logger().info(\"Creating container for image: {}\", dockerImageName);\n            CreateContainerCmd createCommand = dockerClient.createContainerCmd(dockerImageName);\n            applyConfiguration(createCommand);\n\n            createCommand.getLabels().putAll(DockerClientFactory.DEFAULT_LABELS);\n\n            boolean reused = false;\n            final boolean reusable;\n            if (shouldBeReused) {\n                if (!canBeReused()) {\n                    throw new IllegalStateException(\"This container does not support reuse\");\n                }\n\n                if (TestcontainersConfiguration.getInstance().environmentSupportsReuse()) {\n                    createCommand\n                        .getLabels()\n                        .put(COPIED_FILES_HASH_LABEL, Long.toHexString(hashCopiedFiles().getValue()));\n\n                    String hash = hash(createCommand);\n\n                    containerId = findContainerForReuse(hash).orElse(null);\n\n                    if (containerId != null) {\n                        logger().info(\"Reusing container with ID: {} and hash: {}\", containerId, hash);\n                        reused = true;\n                    } else {\n                        logger().debug(\"Can't find a reusable running container with hash: {}\", hash);\n\n                        createCommand.getLabels().put(HASH_LABEL, hash);","sourceCodeStart":366,"sourceCodeEnd":402,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/containers/GenericContainer.java#L366-L402","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Remove .withReuse(true) from this container or disable reuse in testcontainers.properties if the container type doesn't support it.","Override canBeReused() to return true in your custom container subclass only if it's safe (deterministic config, no session state).","Use manual labels/fixed names plus Ryuk suppression as an alternative caching strategy.","Ensure copied/mounted files are deterministic so reuse hashing is stable."],"exampleFix":"// before\ncontainer.withReuse(true).start(); // IllegalStateException for this type\n// after\n// drop reuse for this container type:\ncontainer.start();","handlingStrategy":"validation","validationCode":"if (Boolean.parseBoolean(System.getProperty(\"testcontainers.reuse.enable\"))\n        && !containerSupportsReuse(container)) {\n    // start without reuse instead of failing\n}","typeGuard":"null","tryCatchPattern":"try {\n    container.withReuse(true).start();\n} catch (IllegalStateException e) {\n    if (e.getMessage().contains(\"does not support reuse\")) {\n        container.start(); // fallback: no reuse\n    } else throw e;\n}","preventionTips":["Only enable reuse on containers you control or that document reuse support.","Keep container config deterministic (fixed env, stable mounted files).","Reuse is session-independent — never assume data isolation between reused runs."],"tags":["docker","container-reuse","illegal-state"],"backgroundTag":"invalid-state-transition","analyzedSha":"8e549514e3f01c57d70546fbb8599d138f3903e5","analyzedAt":"2026-09-12T14:56:41.227Z","contentChangedAt":"2026-09-12T14:56:41.227Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}