apache/maven · error · RepositoryMetadataResolutionException

{} could not be retrieved from repository: {} due to an erro

Error message

{} could not be retrieved from repository: {} due to an error: {}

What it means

resolveAlways() downloads metadata from a remote repository via getArtifactMetadataFromDeploymentRepository(); when that transfer fails (TransferFailedException from the wagon layer) it is wrapped in RepositoryMetadataResolutionException with this message. The placeholders are the metadata being resolved, the remote repository id, and the transport error. This is a connectivity/credentials/TLS failure against the remote, not a 'metadata not found' case, which is handled separately.

Source

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

                String msg = "Could not write fixed metadata to " + metadataFile + ": " + e.getMessage();
                if (getLogger().isDebugEnabled()) {
                    getLogger().warn(msg, e);
                } else {
                    getLogger().warn(msg);
                }
            }
        }
    }

    @Override
    public void resolveAlways(
            RepositoryMetadata metadata, ArtifactRepository localRepository, ArtifactRepository remoteRepository)
            throws RepositoryMetadataResolutionException {
        File file;
        try {
            file = getArtifactMetadataFromDeploymentRepository(metadata, localRepository, remoteRepository);
        } catch (TransferFailedException e) {
            throw new RepositoryMetadataResolutionException(
                    metadata + " could not be retrieved from repository: " + remoteRepository.getId()
                            + " due to an error: " + e.getMessage(),
                    e);
        }

        try {
            if (file.exists()) {
                Metadata prevMetadata = readMetadata(file);
                metadata.setMetadata(prevMetadata);
            }
        } catch (RepositoryMetadataReadException e) {
            throw new RepositoryMetadataResolutionException(e.getMessage(), e);
        }
    }

    private File getArtifactMetadataFromDeploymentRepository(
            ArtifactMetadata metadata, ArtifactRepository localRepo, ArtifactRepository remoteRepository)
            throws TransferFailedException {

View on GitHub (pinned to e4093d4e12)

Solutions

Test the repository outside Maven: curl -I on the repository URL and on a maven-metadata.xml inside it to confirm reachability and HTTP status
Make the repository/mirror <id> match a <server> entry in settings.xml and update the credentials
Fix proxy (<proxies>) or TLS settings (truststore, javax.net.ssl.trustStore) according to the transport message
If the repository manager was restarting (transient), simply re-run the build; consider routing through an internal mirror for stability

Example fix

<!-- before: repository id 'releases' has no matching server credentials -->
<distributionManagement>
  <repository><id>releases</id><url>https://repo.example.com/releases</url></repository>
</distributionManagement>
<!-- after: add matching credentials in ~/.m2/settings.xml -->
<servers>
  <server>
    <id>releases</id>
    <username>deploy-user</username>
    <password>${env.REPO_TOKEN}</password>
  </server>
</servers>

Defensive patterns

Strategy: try-catch

Validate before calling

// preflight the remote repository before resolving metadata
try {
    java.net.URL url = new java.net.URL(remoteRepository.getUrl());
    java.net.HttpURLConnection c = (java.net.HttpURLConnection) url.openConnection();
    c.setRequestMethod("HEAD");
    c.setConnectTimeout(5000);
    int code = c.getResponseCode(); // 401/403 => fix credentials; IOException => network/proxy
} catch (IOException e) {
    // repository unreachable: fix network/proxy before calling resolveAlways()
}

Try / catch

Catch RepositoryMetadataResolutionException around resolveAlways(); inspect the cause (TransferFailedException) and branch on auth (401/403) vs connection errors; retry once for transient network failures, surface a credentials/proxy error otherwise.

Prevention

Keep settings.xml server ids in sync with every repository and mirror id the build uses.
Smoke-test proxy and TLS configuration per environment with curl before running builds.
Run scheduled jobs with --batch-mode and preconfigured credentials so failures are loud, not interactive hangs.
Prefer an internal mirror for both availability and consistent authentication.

When it happens

Trigger: Calling resolveAlways(metadata, localRepository, remoteRepository) when the repository URL is unreachable, a proxy blocks the connection, the TLS handshake fails, or the server rejects the request with 401/403 (missing or wrong credentials for the server id).

Common situations: Corporate proxy or missing mirror in settings.xml; a server id in the build not matching any <server> entry in settings.xml; expired or rotated credentials against Nexus/Artifactory; repository manager down or returning 502; self-signed certificate not in the JDK truststore.

Related errors

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