testcontainers/testcontainers-java · info

Consider using "LocalStackContainer(DockerImageName…

Error message

Consider using "LocalStackContainer(DockerImageName dockerImageName, boolean legacyMode)" constructor if you want to disable legacy mode.

What it means

Emitted immediately after the non-semantic-version warning in shouldRunInLegacyMode: Testcontainers falls back to legacy mode for LocalStack images whose tag it cannot parse, and suggests using the two-argument constructor LocalStackContainer(DockerImageName, boolean legacyMode) to explicitly choose the mode instead of relying on version inference. It is a hint, not a failure by itself; the resulting behavior change is that legacy mode is enabled.

Solutions

Switch to new LocalStackContainer(DockerImageName.parse("localstack/localstack:X.Y.Z"), false) to disable legacy mode explicitly
Pin a semantic version so mode inference works correctly
Verify expected behavior after the change: legacy mode changes env vars and single vs multiple container setup

Example fix

// before
LocalStackContainer ls = new LocalStackContainer(DockerImageName.parse("localstack/localstack:latest"));
// after
LocalStackContainer ls = new LocalStackContainer(DockerImageName.parse("localstack/localstack:latest"), false);

Defensive patterns

Strategy: validation

Prevention

Prefer the explicit two-arg constructor LocalStackContainer(image, legacyMode) over version inference
Migrate away from legacy-mode-only configuration when moving to modern LocalStack images
Treat this hint in logs as a prompt to make image tags deterministic

When it happens

Trigger: Same as the non-semantic version fallback: constructing LocalStackContainer with :latest/:nightly/custom tags; the single-arg (or default) constructor path cannot infer the mode and warns with this hint.

Common situations: Using floating image tags in CI; migrating code written for pre-0.11 LocalStack to modern images while keeping a non-semantic tag.

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

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

Appendix: source

Thrown at modules/localstack/src/main/java/org/testcontainers/containers/localstack/LocalStackContainer.java:176

        return true;
    }

    static boolean shouldRunInLegacyMode(String version) {
        // assume that the latest images are up-to-date
        // also consider images with extra packages (like latest-bigdata) and service-specific images (like s3-latest)
        if (version.equals("latest") || version.startsWith("latest-") || version.endsWith("-latest")) {
            return false;
        }

        ComparableVersion comparableVersion = new ComparableVersion(version);
        if (comparableVersion.isSemanticVersion()) {
            boolean versionRequiresLegacyMode = comparableVersion.isLessThan("0.11");
            return versionRequiresLegacyMode;
        }

        log.warn("Version {} is not a semantic version, LocalStack will run in legacy mode.", version);
        log.warn(
            "Consider using \"LocalStackContainer(DockerImageName dockerImageName, boolean legacyMode)\" constructor if you want to disable legacy mode."
        );
        return true;
    }

    @Override
    protected void configure() {
        super.configure();

        if (this.servicesEnvVarRequired) {
            Preconditions.check("services list must not be empty", !services.isEmpty());
        }

        if (!services.isEmpty()) {
            withEnv("SERVICES", services.stream().map(EnabledService::getName).collect(Collectors.joining(",")));
            if (this.servicesEnvVarRequired) {
                withEnv("EAGER_SERVICE_LOADING", "1");
            }

View on GitHub (pinned to 8e549514e3)