project-local-repo clean race condition when root pom has parent

[seregamorph]

Affected version

4.0.0-rc-6

Bug description

Maven 4 creates target/project-local-repo under the root project directory, which contains built JAR artifacts and there is a preference to use them in case of module subset builds.
The directory location assumes that the root project is also a root parent for other modules and if it's not, there is a race condition to clean this directory.

How to reproduce the problem:

• root pom.xml should have a parent, let's call it super-pom/pom.xml
• the super-pom/pom.xml should have other direct child modules, which do not inherit root pom.xml
• build the multi-module project as a parallel build, like ./mvnw clean install -T1C
• the MultiThreadedBuilder will schedule super-pom/pom.xml as a first project to build in the reactor, it finishes alone
• then, in parallel it starts building root pom.xml and other modules which define super-pom as direct parent
• maven-clean-plugin of root pom.xml iterates files for removal
• at the same time(!) other modules start adding file under $projectRoot/target/project-local-repo
• maven-clean-plugin rechecks that target is empty and fails:

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-clean-plugin:3.5.0:clean (default-clean) 
on project pt: Failed to clean project: Failed to delete /Users/..../server/target/project-local-repo -> [Help 1]

(the root project is called pt). See timeline diagram that demonstrates this (pt-clean is long and executed in parallel):

This is a 100% reproducible for a project with the big number of modules.

[desruisseaux]

Just by curiosity, do you know if the bug is also present with maven-clean-plugin:4.0.0-beta-2?

[seregamorph]

I rechecked to reinsure (yes, it's present). But as far as I can see, it's not a bug of the plugin itself. It's a race condition of multi-module build because root project != super project, due to the specific of how MultiThreadedBuilder schedules the reactor (used by default with more than 1 threads: -T1C)

[gnodet]

Proposal: move project-local-repo from target/ to .mvn/

Root cause

The race condition happens because project-local-repo lives inside the root project's target/ directory. During parallel clean install, there is no ordering guarantee between the root project's clean phase (which deletes target/) and sibling modules completing their build (which write artifacts into target/project-local-repo). Since clean and install are in the same TaskSegment, they execute concurrently across projects — the root's maven-clean-plugin and the modules' install can race.

A lock-based approach (e.g. ReadWriteLock in ReactorReader) prevents the crash but does not guarantee ordering — a module could install artifacts before the root's clean runs, only to have them wiped.

Proposal

Move project-local-repo from target/project-local-repo to .mvn/project-local-repo.

This eliminates the race entirely: maven-clean-plugin deletes target/, but never touches .mvn/. The lifecycle of project-local-repo is then fully owned by ReactorReader, which already has cleanProjectLocalRepository() — it just needs to wipe the whole directory at the start of the build (before the executor graph runs), rather than doing per-project GAV cleanup during each project's clean phase.

Precedent

Storing build-related data outside target/ (surviving clean) is an established pattern:

• Maven Build Cache Extension — stores cache in ~/.m2/.cache/maven-build-cache
• Develocity Maven Extension — local cache in ~/.m2/.develocity/
• Gradle — .gradle/ directory at project root stores build metadata, universally gitignored

Trade-offs

• Git: .mvn/ is typically a tracked directory. Users (or Maven itself) would need to add .mvn/project-local-repo to .gitignore. This follows the Gradle convention where .gradle/ is universally gitignored.
• mvn clean semantics: clean would no longer wipe project-local-repo as a side effect. Instead, ReactorReader owns the cleanup explicitly — which is arguably more correct, since it already owns the creation.
• Stale artifacts: Without the implicit clean via target/ deletion, stale artifacts from previous builds could persist. ReactorReader should wipe the directory at the start of a build session that includes a clean phase.

[seregamorph]

@gnodet do I understand correctly that there are reasons why the moduleDir/target/module.jar are not used, and the 3rd copy of .jar files (target of module, .m2/repository and now $rootDir/target/project-local-repo) was introduced. Something like "we cannot be sure that target directory is clean enough to get artifacts from it".
I was solving a pretty similar problem and introduced https://github.com/maven-turbo-reactor/maven-local-workspace-reader , the extension which switches the WorkspaceReader to LocalReactorWorkspaceReader if the JAR artifact of the module is available, see https://github.com/maven-turbo-reactor/maven-local-workspace-reader/blob/master/src/main/java/com/github/seregamorph/maven/extension/local/LocalReactorRepositorySessionDecorator.java . Is it a considerable option to make such behavior in Maven 4? It works quite well for our goals, e.g. you can run mvn package -DskipTests, and then, in a separate command mvn surefire:test -pl :single-module - it resolves JAR dependencies from the other modules target directories, not .m2/repository. This is crucial e.g. when you have multiple git worktrees for the same project.

Curious on your opinion.

cc @cstamas

[gnodet]

The project-local-repo was introduced in MNG-7629 to solve several problems that direct moduleDir/target/ resolution can't handle:

• Subtree/partial builds: mvn -pl :child-2 doesn't have child-1 in the reactor — project-local-repo makes its artifacts available without installing to ~/.m2/repository
• Attached and classified artifacts: the direct target/ fallback only resolves target/classes — it can't find sources.jar, javadoc.jar, test-jars, or any classified artifact. project-local-repo stores them all in repository layout.
• Consumer POMs: project-local-repo stores both build and consumer POM variants
• Resumable builds: mvn install -rf :module-C resolves modules A and B from the previous successful run

Your LocalReactorWorkspaceReader approach works well for the main JAR case, but the cases above are why the full repository-layout copy is needed.

Regarding the proposal to move to .mvn/project-local-repo — this addresses the race condition by taking it out of target/ entirely, so maven-clean-plugin can't interfere. ReactorReader would then fully own its lifecycle (creation, cleanup, and resolution).

[gnodet]

Regarding your extension's use case specifically — project-local-repo in Maven 4 should already cover it:

1. mvn package -DskipTests → all modules build successfully → ReactorReader copies artifacts into project-local-repo
2. mvn surefire:test -pl :single-module → ReactorReader resolves dependencies from project-local-repo without needing sibling modules in the reactor

And your git worktree concern is actually an argument for project-local-repo — each worktree gets its own isolated copy (under its own root directory), unlike ~/.m2/repository which is shared globally across all worktrees.

So your extension should no longer be needed in Maven 4.

[seregamorph]

@gnodet, got it, thanks for the clarifications. Indeed, in Maven 4 this extension is not needed anymore.

BTW, one more approach where to store the files is $HOME/.m2/local-repository/${projectName}_${directoryNameHash}
The similar approach is used in IntelliJ IDEA - it stores project files outside of the main project directory, and this way it can distinguish different copies of the same project. The ${projectName}_ prefix simplifies directory navigation when you inspect caches, the hash suffix makes this binding unique:

ls -1 ~/Library/Caches/JetBrains/IntelliJIdea2026.2/projects
maven-timeline-extension.c1ef30cd
maven-turbo-builder.a8735f92
server.3c4116a1
spring-test-smart-context.e026fed8

This approach solves both problems - the race condition (of $rootModule/target/project-local-repo) and possible non-git ignored files (of $rootModule/.mvn/project-local-repo)

[gnodet]

The ~/.m2/ approach is interesting — IntelliJ's pattern works well for IDE caches. A few concerns for Maven though:

• Hard links break across volumes: ReactorReader already uses hard links (Files.createLink) with a copy fallback. If ~/.m2/ is on a different filesystem than the project (common in CI, Docker mount setups), every artifact becomes a full copy instead of a near-free hard link.
• Stale cache accumulation: when you delete, move, or rename a project, the ~/.m2/local-repository/${name}_${hash} directory lingers forever with no cleanup mechanism. With .mvn/, the cache is self-contained — delete the project, the cache goes with it.
• CI containers: ~/.m2/ is often a shared/cached volume across builds. Project-local-repo artifacts from different builds would accumulate there.
• Loses project locality: harder to inspect and debug. With .mvn/project-local-repo it's right there in the project tree.

The .gitignore concern with .mvn/ is real but manageable — Gradle has the same pattern with .gradle/ being universally gitignored, and it works well in practice. Maven could document the convention or even auto-append the entry.