{"record":{"id":"4615dfbd9178bfb9","repo":"testcontainers/testcontainers-java","slug":"can-t-instantiate-a-strategy-from-classnotfoundexception","errorCode":null,"errorMessage":"Can't instantiate a strategy from {} (ClassNotFoundException). This probably means that cached configuration refers to a client provider class that is not available in this version of Testcontainers. Other strategies will be tried instead.","messagePattern":"Can't instantiate a strategy from (.+?) \\(ClassNotFoundException\\)\\. This probably means that cached configuration refers to a client provider class that is not available in this version of Testcontainers\\. Other strategies will be tried instead\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"core/src/main/java/org/testcontainers/dockerclient/DockerClientProviderStrategy.java","lineNumber":364,"sourceCode":"    }\n\n    private static Optional<? extends DockerClientProviderStrategy> loadConfiguredStrategy() {\n        String configuredDockerClientStrategyClassName = TestcontainersConfiguration\n            .getInstance()\n            .getDockerClientStrategyClassName();\n\n        return Stream\n            .of(configuredDockerClientStrategyClassName)\n            .filter(Objects::nonNull)\n            .flatMap(it -> {\n                try {\n                    Class<? extends DockerClientProviderStrategy> strategyClass = (Class) Thread\n                        .currentThread()\n                        .getContextClassLoader()\n                        .loadClass(it);\n                    return Stream.of(strategyClass.newInstance());\n                } catch (ClassNotFoundException e) {\n                    log.warn(\n                        \"Can't instantiate a strategy from {} (ClassNotFoundException). \" +\n                        \"This probably means that cached configuration refers to a client provider \" +\n                        \"class that is not available in this version of Testcontainers. Other \" +\n                        \"strategies will be tried instead.\",\n                        it\n                    );\n                    return Stream.empty();\n                } catch (InstantiationException | IllegalAccessException e) {\n                    log.warn(\"Can't instantiate a strategy from {}\", it, e);\n                    return Stream.empty();\n                }\n            })\n            // Ignore persisted strategy if it's not persistable anymore\n            .filter(DockerClientProviderStrategy::isPersistable)\n            .peek(strategy -> {\n                log.info(\n                    \"Loaded {} from ~/.testcontainers.properties, will try it first\",\n                    strategy.getClass().getName()","sourceCodeStart":346,"sourceCodeEnd":382,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/dockerclient/DockerClientProviderStrategy.java#L346-L382","documentation":"Testcontainers caches the DockerClientProviderStrategy that last worked (e.g. in ~/.testcontainers.properties). On a later run it tries to reflectively load the class named in that cache; if the class no longer exists in the current Testcontainers version (strategy removed/renamed), this warning is logged and other strategies are tried. It is non-fatal: the library falls back to discovering a valid strategy.","triggerScenarios":"loadConfiguredStrategy reads a cached strategy class name from ~/.testcontainers.properties (docker.client.strategy key) and ClassLoader.loadClass throws ClassNotFoundException during getFirstValidStrategy.","commonSituations":"Upgrading Testcontainers to a version that removed or repackaged a strategy class; a strategy from a different artifact (e.g. custom extension) no longer on the classpath; manually edited testcontainers.properties.","solutions":["Delete or update the docker.client.strategy entry in ~/.testcontainers.properties so auto-discovery picks a current strategy","Upgrade/downgrade so the referenced strategy class exists on the classpath (e.g. add the extension jar that provides it)","Ignore the warning if auto-discovery subsequently logs a valid strategy"],"exampleFix":"// before (~/.testcontainers.properties)\ndocker.client.strategy=org.testcontainers.dockerclient.UnixSocketClientProviderStrategy\n// after: remove the line or set a class present in your version\ndocker.client.strategy=org.testcontainers.dockerclient.TransportConfigStrategy","handlingStrategy":"fallback","validationCode":"Path props = Paths.get(System.getProperty(\"user.home\"), \".testcontainers.properties\");\nif (Files.exists(props)) {\n    String s = java.util.Properties.class.cast(new Object()).toString(); // placeholder\n}\n// check before running: grep docker.client.strategy ~/.testcontainers.properties and confirm the class is on the classpath","typeGuard":null,"tryCatchPattern":"try {\n    Class.forName(cachedStrategyClass).getDeclaredConstructor().newInstance();\n} catch (ClassNotFoundException | ReflectiveOperationException e) {\n    // fall back to default strategy discovery\n}","preventionTips":["Don't hand-edit ~/.testcontainers.properties strategy entries","After upgrading Testcontainers, delete stale cached config","Keep custom strategy artifacts on the runtime classpath"],"tags":["testcontainers","configuration-cache","reflection","classpath"],"backgroundTag":"class-not-found","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"}