apache/maven · error · RepositoryMetadataDeploymentException

Error installing metadata: {}

Error message

Error installing metadata: {}

What it means

During deploy(), after fetching previous metadata, Maven merges the new metadata into the local repository copy via metadata.storeInLocalRepository(...); a RepositoryMetadataStoreException there is wrapped as RepositoryMetadataDeploymentException with the store error appended to 'Error installing metadata'. It is a local-repository write/merge failure occurring immediately before the remote upload step.

Source

Thrown at compat/maven-compat/src/main/java/org/apache/maven/artifact/repository/metadata/DefaultRepositoryMetadataManager.java:417

            if (file.isFile()) {
                try {
                    fixTimestamp(file, readMetadata(file), repositoryMetadata.getMetadata());
                } catch (RepositoryMetadataReadException e) {
                    // will be reported via storeInlocalRepository
                }
            }
        } else {
            // It's a POM - we don't need to retrieve it first
            file = new File(
                    localRepository.getBasedir(),
                    localRepository.pathOfLocalRepositoryMetadata(metadata, deploymentRepository));
        }

        try {
            metadata.storeInLocalRepository(localRepository, deploymentRepository);
        } catch (RepositoryMetadataStoreException e) {
            throw new RepositoryMetadataDeploymentException("Error installing metadata: " + e.getMessage(), e);
        }

        try {
            wagonManager.putArtifactMetadata(file, metadata, deploymentRepository);
        } catch (TransferFailedException e) {
            throw new RepositoryMetadataDeploymentException("Error while deploying metadata: " + e.getMessage(), e);
        }
    }

    @Override
    public void install(ArtifactMetadata metadata, ArtifactRepository localRepository)
            throws RepositoryMetadataInstallationException {
        try {
            metadata.storeInLocalRepository(localRepository, localRepository);
        } catch (RepositoryMetadataStoreException e) {
            throw new RepositoryMetadataInstallationException("Error installing metadata: " + e.getMessage(), e);
        }
    }

View on GitHub (pinned to e4093d4e12)

Solutions

1. Act on the appended store error: fix permissions (chown -R) or free disk space on the local repository volume
2. Delete the local maven-metadata.xml for the artifact being deployed so the merge starts from a clean state
3. Give each concurrent build its own local repository via -Dmaven.repo.local=<dir>
4. Re-run mvn deploy once the local repository is writable and consistent

Example fix

# before: deploy fails merging metadata into root-owned local repo
ls -ld ~/.m2/repository/com/example/art
# after: repair ownership and retry
sudo chown -R $(id -u):$(id -g) ~/.m2/repository
mvn deploy

File localMetadata = new File(localRepository.getBasedir(),
        localRepository.pathOfLocalRepositoryMetadata(metadata, deploymentRepository));
if (localMetadata.isFile() && !localMetadata.canWrite()) { /* repair permissions before deploy */ }
if (!new File(localRepository.getBasedir()).canWrite()) { /* local repo read-only */ }

Catch RepositoryMetadataDeploymentException and use the message prefix to route the fix: 'Error installing metadata' = local repository problem (permissions/corrupt merge/disk); 'Error while deploying metadata' = remote upload problem.

When it happens

Trigger: mvn deploy where the local maven-metadata.xml being merged is corrupt, the local repository directory is read-only or full, or a concurrent build holds/locks the metadata file while storeInLocalRepository writes it.

Common situations: ~/.m2/repository owned by root after running Maven once with sudo; two CI jobs sharing one local repository; corrupt local metadata left by an earlier failed deploy.

Related errors

• Cannot read metadata from '{}': {}
• Error while deploying metadata: {}
• Range defies version ordering: {}
• {} could not be retrieved from repository: {} due to an erro
• Error copying POM to the local repository.

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