{"record":{"id":"ab04e50754325991","repo":"testcontainers/testcontainers-java","slug":"configured-imagepullpolicy-could-not-be-loaded","errorCode":null,"errorMessage":"Configured ImagePullPolicy could not be loaded: ${imagePullPolicyClassName}","messagePattern":"Configured ImagePullPolicy could not be loaded: (.+?)","errorType":"exception","errorClass":"java.lang.IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/testcontainers/images/PullPolicy.java","lineNumber":46,"sourceCode":"    public static synchronized ImagePullPolicy defaultPolicy() {\n        if (instance != null) {\n            return instance;\n        }\n\n        String imagePullPolicyClassName = TestcontainersConfiguration.getInstance().getImagePullPolicy();\n        if (imagePullPolicyClassName != null) {\n            log.debug(\"Attempting to instantiate an ImagePullPolicy with class: {}\", imagePullPolicyClassName);\n            ImagePullPolicy configuredInstance;\n            try {\n                configuredInstance =\n                    (ImagePullPolicy) Thread\n                        .currentThread()\n                        .getContextClassLoader()\n                        .loadClass(imagePullPolicyClassName)\n                        .getDeclaredConstructor()\n                        .newInstance();\n            } catch (Exception e) {\n                throw new IllegalArgumentException(\n                    \"Configured ImagePullPolicy could not be loaded: \" + imagePullPolicyClassName,\n                    e\n                );\n            }\n\n            log.info(\"Found configured Image Pull Policy: {}\", configuredInstance.getClass());\n\n            instance = configuredInstance;\n        } else {\n            instance = defaultImplementation;\n        }\n\n        log.info(\"Image pull policy will be performed by: {}\", instance);\n\n        return instance;\n    }\n\n    /**","sourceCodeStart":28,"sourceCodeEnd":64,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/images/PullPolicy.java#L28-L64","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Correct the image.pull.policy value to the fully-qualified class name of a class with a public no-arg constructor implementing ImagePullPolicy","Add the artifact/module containing the class to the runtime classpath","Make sure the class implements org.testcontainers.images.ImagePullPolicy and has a no-argument constructor","Remove the property to fall back to the built-in default pull policy"],"exampleFix":"// before\nclass MyPolicy implements ImagePullPolicy { public MyPolicy(String cfg) {...} }\nimage.pull.policy=com.example.MyPolicy\n// after\nclass MyPolicy implements ImagePullPolicy { public MyPolicy() {...} }\nimage.pull.policy=com.example.MyPolicy","handlingStrategy":"validation","validationCode":"String cls = System.getProperty(\"image.pull.policy\",\n    System.getenv(\"TESTCONTAINERS_IMAGE_PULL_POLICY\"));\nif (cls != null) {\n    try {\n        Class<?> c = Thread.currentThread().getContextClassLoader().loadClass(cls);\n        c.getDeclaredConstructor(); // throws if no no-arg constructor\n        org.testcontainers.images.ImagePullPolicy.class.cast(\n            c.getDeclaredConstructor().newInstance());\n    } catch (Exception e) {\n        throw new IllegalStateException(\"image.pull.policy class unusable: \" + cls, e);\n    }\n}","typeGuard":"static boolean isLoadablePullPolicy(String name) {\n    try {\n        Class<?> c = Class.forName(name, false,\n            Thread.currentThread().getContextClassLoader());\n        return org.testcontainers.images.ImagePullPolicy.class.isAssignableFrom(c)\n            && java.util.Arrays.stream(c.getConstructors())\n                .anyMatch(ctor -> ctor.getParameterCount() == 0);\n    } catch (Exception e) { return false; }\n}","tryCatchPattern":"try {\n    PullPolicy.defaultPolicy();\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"could not be loaded\")) {\n        // clear the image.pull.policy property and use the built-in default\n    } else throw e;\n}","preventionTips":["Use fully-qualified class names with exact package spelling","Ensure a public no-arg constructor on custom policies","Confirm the policy class is on the runtime classpath of every module using it","Keep policy classes in a shared test-fixtures artifact, not in a single test module"],"tags":["config","reflection","class-not-found","testcontainers"],"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"}