testcontainers/testcontainers-java · warning

Version is not a semantic version. The function…

Error message

Version {} is not a semantic version. The function "withDatabase" will fail.

What it means

Neo4jContainer.isNeo4jDatabaseVersionSupportingDbCopy logs a warning when the Docker image version string cannot be parsed as a semantic version (major.minor.patch). Because db copy support is decided by comparing versions, an unparseable version means withDatabase (which relies on database copying) cannot be evaluated and will likely fail. The method then returns false.

Solutions

1. Pin the image to a full semantic version tag, e.g. neo4j:5.12.0 instead of neo4j:latest.
2. If using withDatabase(), verify the chosen version actually supports db copy (3.5.x).
3. Check the tag for unexpected suffixes and use the plain x.y.z portion.

Example fix

// before
new Neo4jContainer(DockerImageName.parse("neo4j:latest")).withDatabase("copyTarget");
// after
new Neo4jContainer(DockerImageName.parse("neo4j:3.5.22")).withDatabase("copyTarget");

String version = imageTag; // e.g. "5.12.0"
if (!version.matches("^\d+\.\d+\.\d+.*$")) {
    throw new IllegalArgumentException("Pin the Neo4j image to a semantic version, got: " + version);
}

boolean isSemanticVersionTag(String tag) {
    return tag != null && tag.matches("^\d+\.\d+\.\d+.*$");
}

When it happens

Trigger: Using a Neo4j Docker image tag that is not a semantic version (e.g. 'latest', 'enterprise-nightly', '4.4' without patch) and calling withDatabase() on the container.

Common situations: Pointing at 'latest' or floating image tags; custom/renamed registry tags; enterprise images with suffixes that defeat version parsing.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Cannot use enterprise version with alternative image
• This container's image does not have a healthcheck…
• is not a valid Docker image name (in )
• is not a valid image versioning identifier (in )
• anyOthers parameter must be non-empty

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

Appendix: source

Thrown at modules/neo4j/src/main/java/org/testcontainers/neo4j/Neo4jContainer.java:318

    private static String formatConfigurationKey(String plainConfigKey) {
        final String prefix = "NEO4J_";

        return String.format("%s%s", prefix, plainConfigKey.replaceAll("_", "__").replaceAll("\\.", "_"));
    }

    private boolean isNeo4jDatabaseVersionSupportingDbCopy() {
        String usedImageVersion = DockerImageName.parse(getDockerImageName()).getVersionPart();
        ComparableVersion usedComparableVersion = new ComparableVersion(usedImageVersion);

        boolean versionSupportingDbCopy =
            usedComparableVersion.isLessThan("4.0") && usedComparableVersion.isGreaterThanOrEqualTo("2");

        if (versionSupportingDbCopy) {
            return true;
        }
        if (!usedComparableVersion.isSemanticVersion()) {
            logger()
                .warn(
                    "Version {} is not a semantic version. The function \"withDatabase\" will fail.",
                    usedImageVersion
                );
            logger().warn("Copying databases is only supported for Neo4j versions 3.5.x");
        }

        return false;
    }

    public Neo4jContainer withRandomPassword() {
        return withAdminPassword(UUID.randomUUID().toString());
    }
}

View on GitHub (pinned to 8e549514e3)