apache/maven · error · RepositoryMetadataDeploymentException

Error while deploying metadata: {}

Error message

Error while deploying metadata: {}

What it means

The final step of deploy() uploads the merged metadata file with wagonManager.putArtifactMetadata(...); a TransferFailedException there is rethrown as RepositoryMetadataDeploymentException with 'Error while deploying metadata' plus the transport message. This is a push-side failure against the deployment repository: most often authorization (401/403), a read-only or misconfigured repository, or a dropped connection during the PUT.

Source

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

                }
            }
        } 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. Confirm the distributionManagement URL points at a hosted, deployable repository - not a mirror or group endpoint
2. Fix the settings.xml <server> credentials for the distributionManagement repository id
3. Check the repository manager logs for the failed PUT: permission denied, quota exceeded, or deployment policy blocking the upload
4. Retry the deploy after fixing; if a partial upload happened, remove the partial directory on the server and redeploy

Example fix

<!-- before: deploying into a group repository (read-only aggregate) -->
<distributionManagement>
  <repository><id>public</id><url>https://repo.example.com/repository/public/</url></repository>
</distributionManagement>
<!-- after: deploy to the hosted repository -->
<distributionManagement>
  <repository><id>releases-hosted</id><url>https://repo.example.com/repository/releases-hosted/</url></repository>
</distributionManagement>

// probe deploy permission with a throwaway file before the real deploy
java.net.HttpURLConnection c = (java.net.HttpURLConnection) new java.net.URL(
        deployUrl + "/.deploy-probe-" + System.currentTimeMillis()).openConnection();
c.setDoOutput(true);
c.setRequestMethod("PUT");
try (java.io.OutputStream os = c.getOutputStream()) { os.write(0); }
int status = c.getResponseCode(); // 2xx = writable; 401/403 = fix credentials; 405 = read-only endpoint

Catch RepositoryMetadataDeploymentException whose message starts with 'Error while deploying metadata'; read the cause TransferFailedException for the HTTP status; 401/403 -> credentials, 405/read-only -> wrong repository endpoint, IO -> network.

When it happens

Trigger: mvn deploy reaching the metadata upload when the deploy user lacks write permission on the repository, credentials are wrong or missing, the target repository is a read-only mirror/group endpoint instead of a hosted repository, or the connection fails mid-upload.

Common situations: Deploying to a Nexus/Artifactory group or mirror URL instead of a hosted repository; CI credential rotation leaving stale tokens; disk quota exceeded on the repository manager; write policy of the hosted repo set to disable puts.

Related errors

• Error installing metadata: {}
• Could not write fixed metadata to {}: {}
• Cannot read metadata from '{}': {}
• {} could not be retrieved from repository: {} due to an erro
• Cannot add two different pieces of metadata for: " + getKey(

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