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 Local Operation Failed

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

The remote service may be fine. This class of error is usually about what the local machine was allowed to read, write, cache, or execute.

Fix the local path, cache, or permissions

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.

Manual filesystem checks

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

Why the Local Machine Blocked It

Usually this comes down to 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, or custom local repository path (-Dmaven.repo.local=...) points to a non-writable location.

Verify the Local Path Is Usable Again

Re-run mvn -DskipTests package and confirm Maven downloads artifacts and writes them under the local repository path, and confirm new directories appear under ~/.m2/repository/ (or your custom maven.repo.local).

How Maven uses the local repository

This is the part worth understanding if the quick fix did not hold. It explains what Maven is trying to do at the moment the error appears.

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.

Prevent Local State Drift

To prevent this, 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, and monitor disk space on CI runners to prevent hidden cache failures.

Examples

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

Docs and source code

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);