testcontainers/testcontainers-java · warning

Can't instantiate a strategy from

Error message

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.

What it means

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.

Solutions

  1. Delete or update the docker.client.strategy entry in ~/.testcontainers.properties so auto-discovery picks a current strategy
  2. Upgrade/downgrade so the referenced strategy class exists on the classpath (e.g. add the extension jar that provides it)
  3. Ignore the warning if auto-discovery subsequently logs a valid strategy

Example fix

// before (~/.testcontainers.properties)
docker.client.strategy=org.testcontainers.dockerclient.UnixSocketClientProviderStrategy
// after: remove the line or set a class present in your version
docker.client.strategy=org.testcontainers.dockerclient.TransportConfigStrategy
Defensive patterns

Strategy: fallback

Validate before calling

Path props = Paths.get(System.getProperty("user.home"), ".testcontainers.properties");
if (Files.exists(props)) {
    String s = java.util.Properties.class.cast(new Object()).toString(); // placeholder
}
// check before running: grep docker.client.strategy ~/.testcontainers.properties and confirm the class is on the classpath

Try / catch

try {
    Class.forName(cachedStrategyClass).getDeclaredConstructor().newInstance();
} catch (ClassNotFoundException | ReflectiveOperationException e) {
    // fall back to default strategy discovery
}

Prevention

When it happens

Trigger: loadConfiguredStrategy reads a cached strategy class name from ~/.testcontainers.properties (docker.client.strategy key) and ClassLoader.loadClass throws ClassNotFoundException during getFirstValidStrategy.

Common situations: 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.

Related errors

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

Appendix: source

Thrown at core/src/main/java/org/testcontainers/dockerclient/DockerClientProviderStrategy.java:364

    }

    private static Optional<? extends DockerClientProviderStrategy> loadConfiguredStrategy() {
        String configuredDockerClientStrategyClassName = TestcontainersConfiguration
            .getInstance()
            .getDockerClientStrategyClassName();

        return Stream
            .of(configuredDockerClientStrategyClassName)
            .filter(Objects::nonNull)
            .flatMap(it -> {
                try {
                    Class<? extends DockerClientProviderStrategy> strategyClass = (Class) Thread
                        .currentThread()
                        .getContextClassLoader()
                        .loadClass(it);
                    return Stream.of(strategyClass.newInstance());
                } catch (ClassNotFoundException e) {
                    log.warn(
                        "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.",
                        it
                    );
                    return Stream.empty();
                } catch (InstantiationException | IllegalAccessException e) {
                    log.warn("Can't instantiate a strategy from {}", it, e);
                    return Stream.empty();
                }
            })
            // Ignore persisted strategy if it's not persistable anymore
            .filter(DockerClientProviderStrategy::isPersistable)
            .peek(strategy -> {
                log.info(
                    "Loaded {} from ~/.testcontainers.properties, will try it first",
                    strategy.getClass().getName()

View on GitHub (pinned to 8e549514e3)