What causes "Version {} is not a semantic version. The function "withDatabase" will fail." in testcontainers/testcontainers-java?

Pin a semver image tag; for db-copy support specifically use Neo4j 3.5.x (e.g. neo4j:3.5.35)

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

isNeo4jDatabaseVersionSupportingDbCopy determines whether withDatabase() can copy the default database to a new named database. Database copy is only supported on Neo4j 3.5.x; if the image's version string is not a semantic version, the check cannot confirm support, logs this warning (db copy will fail), plus a note that copying is only supported for 3.5.x, and returns false so withDatabase will not attempt the copy path.

Solutions

Pin a semver image tag; for db-copy support specifically use Neo4j 3.5.x (e.g. neo4j:3.5.35)
Remove withDatabase() and create/switch databases via Cypher in an init script for Neo4j 4+
Verify the tag parses as semantic version (major.minor.patch)

Example fix

// before
new Neo4jContainer("neo4j:latest").withDatabase("mydb");
// after
new Neo4jContainer("neo4j:3.5.35").withDatabase("mydb");

Defensive patterns

Strategy: validation

Validate before calling

String tag = image.getVersionPart();
boolean semver = tag.matches("\\d+\\.\\d+\\.\\d+.*");
if (!semver || !tag.startsWith("3.5")) {
    // withDatabase() db-copy will not work; plan an init-script alternative
}

Prevention

Only use withDatabase() on Neo4j 3.5.x images pinned with semver tags
Avoid 'latest' or custom non-semver tags when relying on version-dependent features
Provision databases via Cypher init scripts for Neo4j 4+

When it happens

Trigger: Calling neo4j.withDatabase("mydb") on a container whose image version tag is not semantic (e.g. neo4j:latest, neo4j:5-enterprise, custom builds) so usedComparableVersion.isSemanticVersion() is false.

Common situations: Using floating tags like neo4j:latest; enterprise/custom images tagged without strict semver; upgrading images while keeping withDatabase() calls written for 3.5.x.

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/ea02ad462d511190. Report an issue: GitHub.

Appendix: source

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

    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 S withRandomPassword() {
        return withAdminPassword(UUID.randomUUID().toString());
    }
}

View on GitHub (pinned to 8e549514e3)