testcontainers/testcontainers-java · warning

Version is not a semantic version, services list is…

Error message

Version {} is not a semantic version, services list is required.

What it means

LocalStackContainer decides whether the SERVICES environment variable must be set by comparing the image version to 0.13. If the version string extracted from the image is not a parsable semantic version, isServicesEnvVarRequired logs this warning and conservatively returns true, requiring a services list. This is a defensive fallback for custom or oddly tagged LocalStack images.

Solutions

  1. Use a semver-tagged image, e.g. DockerImageName.parse("localstack/localstack:3.4.0")
  2. Always call withServices(LocalStack.Service.S3, ...) so the SERVICES env var is set regardless of the fallback
  3. If using a custom tag, retag or build your image with a semantic version tag

Example fix

// before
LocalStackContainer ls = new LocalStackContainer(DockerImageName.parse("localstack/localstack:latest"));
// after
LocalStackContainer ls = new LocalStackContainer(DockerImageName.parse("localstack/localstack:3.4.0"))
    .withServices(LocalStack.Service.S3, LocalStack.Service.SQS);
Defensive patterns

Strategy: validation

Validate before calling

String tag = imageName.getVersionPart();
if (!tag.matches("\\d+(\\.\\d+)*")) {
    throw new IllegalArgumentException("Use a semantic version tag for localstack, got: " + tag);
}

Prevention

When it happens

Trigger: Constructing LocalStackContainer with a DockerImageName whose version tag is not semantic (e.g. localstack/localstack:latest, custom dates like :2021-03-12, or sha/digest-style tags); static check isServicesEnvVarRequired(version) then hits the non-semantic branch.

Common situations: Pinning localstack/localstack:latest in tests; using a locally built image tagged 'dev' or 'snapshot'; upgrading from an old pattern where arbitrary tags were common.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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

Appendix: source

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

        if (version.equals("latest")) {
            return true;
        }

        ComparableVersion comparableVersion = new ComparableVersion(version);
        return comparableVersion.isGreaterThanOrEqualTo("2.0.0");
    }

    private static boolean isServicesEnvVarRequired(String version) {
        if (version.equals("latest")) {
            return false;
        }

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

        log.warn("Version {} is not a semantic version, services list is required.", version);

        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);

View on GitHub (pinned to 8e549514e3)