What causes "Copying databases is only supported for Neo4j versions 3.5.x" in testcontainers/testcontainers-java?

Use a Neo4j 3.5.x image tag if database copy is required

testcontainers/testcontainers-java · warning

Copying databases is only supported for Neo4j versions 3.5.x

Error message

Copying databases is only supported for Neo4j versions 3.5.x

What it means

Follow-up warning from isNeo4jDatabaseVersionSupportingDbCopy: after failing to confirm a semantic version, Testcontainers logs that copying databases is only supported for Neo4j versions 3.5.x and returns false. Subsequently, withDatabase() will not perform the database-copy operation, so callers relying on it get a container without the extra named database (or a downstream failure) rather than the expected setup.

Solutions

Use a Neo4j 3.5.x image tag if database copy is required
Drop withDatabase() for modern Neo4j and provision databases with an init script executing Cypher (CREATE DATABASE / :use)
Pin a semantic version tag so version detection works

Example fix

// before
new Neo4jContainer("neo4j:5.11").withDatabase("extra"); // unsupported copy
// after (Neo4j 5: create db via init script instead)
new Neo4jContainer("neo4j:5.11")
    .withInitScript("createDb.cypher"); // CREATE DATABASE extra IF NOT EXISTS

Defensive patterns

Strategy: fallback

Validate before calling

String tag = image.getVersionPart();
if (!tag.startsWith("3.5")) {
    // skip withDatabase(); create the database via an init script instead
}

Prevention

Check the Neo4j major version before calling withDatabase()
Use init scripts (Cypher CREATE DATABASE) for Neo4j 4+/5+
Pin images to exact semver tags so version-gated features behave predictably

When it happens

Trigger: withDatabase("name") invoked with a non-semantic or non-3.5.x Neo4j image version; the method short-circuits: versionSupportingDbCopy false -> warn -> return false.

Common situations: Migrating tests from Neo4j 3.5 to 4.x/5.x where withDatabase() was used; custom or 'latest' tagged images where the version cannot be evaluated at all.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

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

    }

    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)