testcontainers/testcontainers-java · warning

Image name was substituted by configuration to . This…

Error message

Image name {} was substituted by configuration to {}. This approach is deprecated and will be removed in the future

What it means

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.

Solutions

1. Remove the image.substituted.* entries from testcontainers.properties and reference the desired image directly in code
2. Use a private registry mirror at the daemon level (registry-mirrors in daemon.json) instead of name substitution
3. Subclass the container module or set the image explicitly in your test fixtures

Example fix

// before (testcontainers.properties)
image.substituted.redis=mirror.internal/redis
// after
new GenericContainer("mirror.internal/redis:7").asCompatibleSubstituteFor("redis");

java.util.Properties props = new java.util.Properties();
try (var in = Files.newInputStream(Paths.get(System.getProperty("user.home"), ".testcontainers.properties"))) {
    props.load(in);
}
String subst = props.stringPropertyNames().stream()
    .filter(k -> k.startsWith("image.substituted."))
    .findFirst().orElse(null);
if (subst != null) log.warn("deprecated image substitution configured: " + subst);

When it happens

Trigger: 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).

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

Understand the failure class

Background: "is deprecated and will be removed" — deprecation warnings for old API names, keywords, and options, and how to migrate before the removal release — this error's family across 29 libraries.

Related errors

• Changing startup timeout is not supported with mode
• Container needs to be initialized
• Elasticsearch and Kibana have different networks…
• Elasticsearch must be configured either via constructor…
• Empty password can be used only with the root user

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

Appendix: source

Thrown at core/src/main/java/org/testcontainers/utility/ConfigurationFileImageNameSubstitutor.java:31

    private final TestcontainersConfiguration configuration;

    public ConfigurationFileImageNameSubstitutor() {
        this(TestcontainersConfiguration.getInstance());
    }

    @VisibleForTesting
    ConfigurationFileImageNameSubstitutor(TestcontainersConfiguration configuration) {
        this.configuration = configuration;
    }

    @Override
    public DockerImageName apply(final DockerImageName original) {
        final DockerImageName result = configuration
            .getConfiguredSubstituteImage(original)
            .asCompatibleSubstituteFor(original);

        if (!result.equals(original)) {
            log.warn(
                "Image name {} was substituted by configuration to {}. This approach is deprecated and will be removed in the future",
                original,
                result
            );
        }

        return result;
    }

    @Override
    protected String getDescription() {
        return getClass().getSimpleName();
    }
}

View on GitHub (pinned to 8e549514e3)