testcontainers/testcontainers-java · error · java.lang.IllegalArgumentException

Configured ImagePullPolicy could not be loaded

Error message

Configured ImagePullPolicy could not be loaded: ${imagePullPolicyClassName}

What it means

Thrown by PullPolicy.defaultPolicy when the ImagePullPolicy implementation class named by the 'image.pull.policy' config property cannot be instantiated: the class is not on the classpath, lacks a no-arg constructor, or its constructor throws. It is wrapped into an IllegalArgumentException by the library.

Solutions

1. Correct the image.pull.policy value to the fully-qualified class name of a class with a public no-arg constructor implementing ImagePullPolicy
2. Add the artifact/module containing the class to the runtime classpath
3. Make sure the class implements org.testcontainers.images.ImagePullPolicy and has a no-argument constructor
4. Remove the property to fall back to the built-in default pull policy

Example fix

// before
class MyPolicy implements ImagePullPolicy { public MyPolicy(String cfg) {...} }
image.pull.policy=com.example.MyPolicy
// after
class MyPolicy implements ImagePullPolicy { public MyPolicy() {...} }
image.pull.policy=com.example.MyPolicy

String cls = System.getProperty("image.pull.policy",
    System.getenv("TESTCONTAINERS_IMAGE_PULL_POLICY"));
if (cls != null) {
    try {
        Class<?> c = Thread.currentThread().getContextClassLoader().loadClass(cls);
        c.getDeclaredConstructor(); // throws if no no-arg constructor
        org.testcontainers.images.ImagePullPolicy.class.cast(
            c.getDeclaredConstructor().newInstance());
    } catch (Exception e) {
        throw new IllegalStateException("image.pull.policy class unusable: " + cls, e);
    }
}

static boolean isLoadablePullPolicy(String name) {
    try {
        Class<?> c = Class.forName(name, false,
            Thread.currentThread().getContextClassLoader());
        return org.testcontainers.images.ImagePullPolicy.class.isAssignableFrom(c)
            && java.util.Arrays.stream(c.getConstructors())
                .anyMatch(ctor -> ctor.getParameterCount() == 0);
    } catch (Exception e) { return false; }
}

try {
    PullPolicy.defaultPolicy();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("could not be loaded")) {
        // clear the image.pull.policy property and use the built-in default
    } else throw e;
}

When it happens

Trigger: Setting TestcontainersConfiguration property image.pull.policy (e.g. in ~/.testcontainers.properties or classpath testcontainers.properties) to a class name that fails ClassLoader.loadClass or newInstance — missing dependency, wrong package/name, no public no-arg constructor, or constructor throwing an Exception.

Common situations: Typo in the fully-qualified class name; the custom policy class lives in test code but is referenced from a module that doesn't see it; class implements the wrong interface or requires constructor arguments; shaded/jar packaging excludes the class.

Related errors

• Unknown transport type
• Invalid value for dockerconfig.source
• HiveMQ config file ' ' does not exist.
• Error while executing init function
• Can't instantiate a strategy from

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

Appendix: source

Thrown at core/src/main/java/org/testcontainers/images/PullPolicy.java:46

    public static synchronized ImagePullPolicy defaultPolicy() {
        if (instance != null) {
            return instance;
        }

        String imagePullPolicyClassName = TestcontainersConfiguration.getInstance().getImagePullPolicy();
        if (imagePullPolicyClassName != null) {
            log.debug("Attempting to instantiate an ImagePullPolicy with class: {}", imagePullPolicyClassName);
            ImagePullPolicy configuredInstance;
            try {
                configuredInstance =
                    (ImagePullPolicy) Thread
                        .currentThread()
                        .getContextClassLoader()
                        .loadClass(imagePullPolicyClassName)
                        .getDeclaredConstructor()
                        .newInstance();
            } catch (Exception e) {
                throw new IllegalArgumentException(
                    "Configured ImagePullPolicy could not be loaded: " + imagePullPolicyClassName,
                    e
                );
            }

            log.info("Found configured Image Pull Policy: {}", configuredInstance.getClass());

            instance = configuredInstance;
        } else {
            instance = defaultImplementation;
        }

        log.info("Image pull policy will be performed by: {}", instance);

        return instance;
    }

    /**

View on GitHub (pinned to 8e549514e3)