Maven "Could not create local repository" - Fix ~/.m2 Permissions

By Daniel Zoghalchali·Latchkey

Maven could not create the local repository directory it caches artifacts in. The configured path is not writable - wrong ownership in a container, a read-only mount, or a bad <localRepository>.

What this error means

Maven fails at startup with Could not create local repository at /path/.m2/repository before resolving anything. The path is unwritable for the user the job runs as.

[ERROR] Could not create local repository at /home/runner/.m2/repository
-> [Help 1]

Common causes

Unwritable or wrong-owner ~/.m2

In a container, the job user may differ from the directory owner, or HOME may be unset, so Maven cannot create ~/.m2/repository.

localRepository points at a read-only path

A <localRepository> in settings.xml (or -Dmaven.repo.local) pointing at a read-only mount or a non-existent parent cannot be created.

How to fix it

Point the local repo at a writable path

Set a job-local, writable repository directory explicitly.

mvn -B -Dmaven.repo.local=$PWD/.m2/repository verify

Fix ownership and HOME in containers

Ensure HOME is set and the .m2 directory is owned by the job user.

export HOME=/root
mkdir -p "$HOME/.m2/repository"
chown -R "$(id -u):$(id -g)" "$HOME/.m2"

How to prevent it

• Set -Dmaven.repo.local to a writable, cacheable path in CI.
• Ensure HOME and ownership are correct for the job user in containers.
• Avoid mounting ~/.m2 read-only when the build must write to it.

Frequently asked questions

Related guides

References

• Apache Maven guides
• Gradle user manual
• GitHub Actions documentation