Could not create local repository

Q: What does maven:LOCAL_REPOSITORY_PERMISSION_DENIED mean?

Maven cannot write to the local repository directory (`~/.m2/repository` by default), usually due to permissions or a read-only filesystem.

Q: How do I prevent maven:LOCAL_REPOSITORY_PERMISSION_DENIED in CI?

Never run Maven as root on developer machines; fix permissions instead. In CI, explicitly set a writable local repository cache location and persist it between runs. Monitor disk space on CI runners to prevent hidden cache failures.

Q: How can I manually validate maven:LOCAL_REPOSITORY_PERMISSION_DENIED?

Check the local repository path Maven will use: `mvn -q help:evaluate -Dexpression=settings.localRepository -DforceStdout`. Confirm the directory exists and is writable by the current user: `ls -la ~/.m2` and `ls -la ~/.m2/repository`. Check free disk space on the filesystem containing `~/.m2`: `df -h`.

What This Error Means

Maven cannot write to the local repository directory (~/.m2/repository by default), usually due to permissions or a read-only filesystem.

How to Fix It

Fix ownership/permissions of the local repo directory (avoid using sudo mvn ...).

If you're in a container/CI, mount a writable volume for ~/.m2 or set a writable local repo path: mvn -Dmaven.repo.local=/tmp/m2 -DskipTests package.

Ensure there is enough disk space and that the filesystem is not read-only.

Retry the original Maven command and confirm Maven can create directories under the local repository path.

Why It Happens

The ~/.m2 directory (or filesystem) is owned by a different user (common after running Maven with sudo).

The filesystem is read-only (containers, locked-down CI runners, sandboxed environments).

Disk is full or quota limits prevent writes.

Custom local repository path (-Dmaven.repo.local=...) points to a non-writable location.

How to Verify

Re-run mvn -DskipTests package and confirm Maven downloads artifacts and writes them under the local repository path.

Confirm new directories appear under ~/.m2/repository/ (or your custom maven.repo.local).

Manual filesystem checks

Check the local repository path Maven will use:mvn -q help:evaluate -Dexpression=settings.localRepository -DforceStdout

Confirm the directory exists and is writable by the current user:ls -la ~/.m2 and ls -la ~/.m2/repository

Check free disk space on the filesystem containing ~/.m2: df -h.

Examples

[ERROR] Could not create local repository at /Users/you/.m2/repository
java.nio.file.AccessDeniedException: /Users/you/.m2/repository

How Maven uses the local repository

Maven caches downloaded artifacts and metadata in a local repository (default:~/.m2/repository).

If Maven cannot create directories or write files there, dependency/plugin resolution fails even if the network and repositories are correct.

Prevention Tips

Never run Maven as root on developer machines, fix permissions instead.

In CI, explicitly set a writable local repository cache location and persist it between runs.

Monitor disk space on CI runners to prevent hidden cache failures.

Where This Can Be Triggered

github.com/apache/maven/blob/maven-3.6.3/maven-core/src/main/java/org/apache/maven/execution/DefaultMavenExecutionRequestPopulator.java

Maven fails early if it cannot create the local repository directory and throws "Could not create local repository at ...". - GitHub

if (!localRepositoryBasedir.exists() && !localRepositoryBasedir.mkdirs()) {
    throw new MavenExecutionRequestPopulationException("Could not create local repository at " + localRepositoryBasedir);
}
request.setLocalRepositoryPath(localRepositoryBasedir);