{"record":{"id":"7f45ade0d9d413a6","repo":"testcontainers/testcontainers-java","slug":"image-name-was-substituted-by-configuration-to-this-approach","errorCode":null,"errorMessage":"Image name {} was substituted by configuration to {}. This approach is deprecated and will be removed in the future","messagePattern":"Image name (.+?) was substituted by configuration to (.+?)\\. This approach is deprecated and will be removed in the future","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"core/src/main/java/org/testcontainers/utility/ConfigurationFileImageNameSubstitutor.java","lineNumber":31,"sourceCode":"    private final TestcontainersConfiguration configuration;\n\n    public ConfigurationFileImageNameSubstitutor() {\n        this(TestcontainersConfiguration.getInstance());\n    }\n\n    @VisibleForTesting\n    ConfigurationFileImageNameSubstitutor(TestcontainersConfiguration configuration) {\n        this.configuration = configuration;\n    }\n\n    @Override\n    public DockerImageName apply(final DockerImageName original) {\n        final DockerImageName result = configuration\n            .getConfiguredSubstituteImage(original)\n            .asCompatibleSubstituteFor(original);\n\n        if (!result.equals(original)) {\n            log.warn(\n                \"Image name {} was substituted by configuration to {}. This approach is deprecated and will be removed in the future\",\n                original,\n                result\n            );\n        }\n\n        return result;\n    }\n\n    @Override\n    protected String getDescription() {\n        return getClass().getSimpleName();\n    }\n}\n","sourceCodeStart":13,"sourceCodeEnd":46,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/utility/ConfigurationFileImageNameSubstitutor.java#L13-L46","documentation":"ConfigurationFileImageNameSubstitutor rewrites image names via the testcontainers.properties image.substituted.* keys. When a substitution changes the name, Testcontainers warns because config-based image overriding is deprecated and will be removed; users should migrate to other mechanisms.","triggerScenarios":"apply() detects the configured substitute image differs from the original whenever any image name is resolved (e.g. GenericContainer(\"redis:7\") with a redis image.substituted entry).","commonSituations":"Teams historically redirecting images to an internal registry via testcontainers.properties; old CI setups pinning patched image versions; inherited config files no one remembers adding.","solutions":["Remove the image.substituted.* entries from testcontainers.properties and reference the desired image directly in code","Use a private registry mirror at the daemon level (registry-mirrors in daemon.json) instead of name substitution","Subclass the container module or set the image explicitly in your test fixtures"],"exampleFix":"// before (testcontainers.properties)\nimage.substituted.redis=mirror.internal/redis\n// after\nnew GenericContainer(\"mirror.internal/redis:7\").asCompatibleSubstituteFor(\"redis\");","handlingStrategy":"validation","validationCode":"java.util.Properties props = new java.util.Properties();\ntry (var in = Files.newInputStream(Paths.get(System.getProperty(\"user.home\"), \".testcontainers.properties\"))) {\n    props.load(in);\n}\nString subst = props.stringPropertyNames().stream()\n    .filter(k -> k.startsWith(\"image.substituted.\"))\n    .findFirst().orElse(null);\nif (subst != null) log.warn(\"deprecated image substitution configured: \" + subst);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Audit testcontainers.properties for image.substituted.* keys","Reference internal registry images directly in code","Use daemon-level registry mirrors instead of substitution"],"tags":["testcontainers","deprecation","image-substitution","configuration"],"backgroundTag":"deprecated-api-usage","analyzedSha":"8e549514e3f01c57d70546fbb8599d138f3903e5","analyzedAt":"2026-09-12T14:56:41.227Z","contentChangedAt":"2026-09-12T14:56:41.227Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}