apache/maven · error · MavenExecutionRequestPopulationException

Cannot create local repository.

Error message

Cannot create local repository.

What it means

MavenExecutionRequestPopulationException thrown while deriving the local repository for a request. DefaultMavenExecutionRequestPopulator computes the path (maven.user.conf property, else ~/.m2/repository) and calls repositorySystem.createLocalRepository; ANY exception from that creation is wrapped as 'Cannot create local repository.' with no further detail in the message.

Source

Thrown at impl/maven-core/src/main/java/org/apache/maven/execution/DefaultMavenExecutionRequestPopulator.java:139

            throws MavenExecutionRequestPopulationException {
        String localRepositoryPath = null;

        if (request.getLocalRepositoryPath() != null) {
            localRepositoryPath = request.getLocalRepositoryPath().getAbsolutePath();
        }

        if (localRepositoryPath == null || localRepositoryPath.isEmpty()) {
            String path = request.getUserProperties().getProperty(Constants.MAVEN_USER_CONF);
            if (path == null) {
                path = request.getSystemProperties().getProperty("user.home") + File.separator + ".m2";
            }
            localRepositoryPath = new File(path, "repository").getAbsolutePath();
        }

        try {
            return repositorySystem.createLocalRepository(new File(localRepositoryPath));
        } catch (Exception e) {
            throw new MavenExecutionRequestPopulationException("Cannot create local repository.", e);
        }
    }

    private void baseDirectory(MavenExecutionRequest request) {
        if (request.getBaseDirectory() == null && request.getPom() != null) {
            request.setBaseDirectory(request.getPom().getAbsoluteFile().getParentFile());
        }
    }

    /*if_not[MAVEN4]*/

    @Override
    @Deprecated
    public MavenExecutionRequest populateFromSettings(MavenExecutionRequest request, Settings settings)
            throws MavenExecutionRequestPopulationException {
        if (settings == null) {
            return request;
        }

View on GitHub (pinned to e4093d4e12)

Solutions

1. Check settings.xml <localRepository>: it must be a creatable directory path, not an existing file
2. Verify the directory exists and is writable: mkdir -p <path> && touch <path>/.probe
3. Redirect to a known-good path for the run: mvn -Dmaven.repo.local=/tmp/repo ...
4. Ensure user.home resolves correctly (set HOME in Docker/CI) so the ~/.m2/repository fallback works

Example fix

<!-- before: points at a regular file or unwritable path -->
<localRepository>/etc/maven/repo.txt</localRepository>

<!-- after: creatable, writable directory -->
<localRepository>/var/maven/repository</localRepository>

// Validate the local repository path before populating the request
Path localRepo = Paths.get(effectiveLocalRepositoryPath); // from settings or default
if (Files.exists(localRepo) && !Files.isDirectory(localRepo)) {
    throw new IllegalStateException("localRepository path is a regular file: " + localRepo);
}
Files.createDirectories(localRepo);
if (!Files.isWritable(localRepo)) {
    throw new IllegalStateException("localRepository is not writable: " + localRepo);
}

try {
    popul.populateDefaults(request);
} catch (MavenExecutionRequestPopulationException e) {
    if (e.getMessage().equals("Cannot create local repository.")) {
        // the cause says why: permissions, path is a file, read-only FS
        throw new IllegalStateException("Fix settings.xml <localRepository>: " + localRepoPath, e.getCause());
    }
    throw e;
}

When it happens

Trigger: populateFromSettings/populateDefaults on a request whose effective local repository path cannot be turned into a repository object: the path exists as a regular file, the directory cannot be created (permissions, read-only filesystem), or the path string is malformed.

Common situations: settings.xml <localRepository> pointing to a file or unwritable location; HOME/user.home unset or odd in containers so the ~/.m2 fallback resolves badly; CI agents with read-only home directories; overridden maven.user.conf property pointing somewhere invalid.

Related errors

• Range defies version ordering: {}
• The artifact has no valid ranges
• Cannot read metadata from '{}': {}
• Error installing metadata: {}
• Error copying POM to the local repository.

AI-assisted analysis of apache/maven@e4093d4e12 (2026-08-21). Data as JSON: /api/errors/80d3cccb4b64dff3. Report an issue: GitHub.