testcontainers/testcontainers-java · error · java.lang.IllegalArgumentException

Copying database folder is not supported for Neo4j…

Error message

Copying database folder is not supported for Neo4j instances with version 4.0 or higher.

What it means

Neo4jContainer.withDatabase(MountableFile) copies a pre-built graph.db folder into the container, but that mechanism only works with Neo4j 3.5. From 4.0 onward the store format and directory layout changed, so the library rejects the call with an IllegalArgumentException rather than mounting an unusable database.

Solutions

Pin the container image to neo4j:3.5 if you must seed via graph.db folder copy.
For 4.0+, seed data with Cypher scripts executed after startup (e.g. via the Bolt driver or container exec) instead of copying graph.db.
Use Neo4j admin dump/load inside the container for newer versions.

Example fix

// before
new Neo4jContainer<>("neo4j:4.4").withDatabase(MountableFile.forClasspathResource("graph.db"));
// after
Neo4jContainer c = new Neo4jContainer<>("neo4j:4.4");
c.start();
// run seed Cypher via driver at bolt://... after start

Defensive patterns

Strategy: validation

Validate before calling

String tag = container.getDockerImageName();
boolean supportsDbCopy = tag.contains(":3.5");
if (!supportsDbCopy) {
    // skip withDatabase(); seed via Cypher after start
}

Try / catch

try {
    container.withDatabase(graphDb);
} catch (IllegalArgumentException e) {
    // seed via Cypher through Bolt after container.start()
}

Prevention

Only use withDatabase() with neo4j:3.5 images.
Adopt Cypher-based seeding for Neo4j 4.x/5.x.
Document the seeding strategy per image version in test infrastructure code.

When it happens

Trigger: Calling withDatabase(graphDbFolder) on a container configured with Neo4j image version 4.0 or newer (isNeo4jDatabaseVersionSupportingDbCopy() returns false).

Common situations: Upgrading tests from Neo4j 3.5 to 4.x/5.x while keeping the old database-seeding call; reusing seed fixtures created for 3.5 against a newer image tag.

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

Appendix: source

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

     * If you want to map your database into the container instead of copying them, please use {@code #withClasspathResourceMapping},
     * but this will only work when your test does not run in a container itself.
     * <br>
     * Note: This method only works with Neo4j 3.5.
     * <br>
     * Mapping would work like this:
     * <pre>
     *      &#64;Container
     *      private static final Neo4jContainer databaseServer = new Neo4jContainer&lt;&gt;()
     *          .withClasspathResourceMapping("/test-graph.db", "/data/databases/graph.db", BindMode.READ_WRITE);
     * </pre>
     *
     * @param graphDb The graph.db folder to copy into the container
     * @throws IllegalArgumentException If the database version is not 3.5.
     * @return This container.
     */
    public S withDatabase(MountableFile graphDb) {
        if (!isNeo4jDatabaseVersionSupportingDbCopy()) {
            throw new IllegalArgumentException(
                "Copying database folder is not supported for Neo4j instances with version 4.0 or higher."
            );
        }
        return withCopyFileToContainer(graphDb, "/data/databases/graph.db");
    }

    /**
     * Adds plugins to the given directory to the container. If {@code plugins} denotes a directory, than all of that
     * directory is mapped to Neo4j's plugins. Otherwise, single resources are copied over.
     * <br>
     * If you want to map your plugins into the container instead of copying them, please use {@code #withClasspathResourceMapping},
     * but this will only work when your test does not run in a container itself.
     *
     * @param plugins
     * @return This container.
     */
    public S withPlugins(MountableFile plugins) {
        return withCopyFileToContainer(plugins, "/var/lib/neo4j/plugins/");

View on GitHub (pinned to 8e549514e3)