What causes "The artifact {} has been relocated to {}" in apache/maven?

Update the dependency declaration in the POM to the relocated coordinates shown in the warning (the part after 'has been relocated to')

apache/maven · warning

The artifact {} has been relocated to {}

Error message

The artifact {} has been relocated to {}

What it means

While collecting the dependency graph, Maven detected that a direct dependency's original coordinates have been relocated by the repository to new coordinates (DependencyNode.getRelocations() is non-empty). Resolution continues against the new location, so this is advisory: nothing fails, but the old coordinates are deprecated and every build re-follows the relocation entries. When the artifact is a RelocatedArtifact, its message (often the reason for the move) is appended to the warning.

Source

Thrown at impl/maven-core/src/main/java/org/apache/maven/project/DefaultProjectDependenciesResolver.java:183

            node = repoSystem.collectDependencies(session, collect).getRoot();
            result.setDependencyGraph(node);
        } catch (DependencyCollectionException e) {
            result.setDependencyGraph(e.getResult().getRoot());
            result.setCollectionErrors(e.getResult().getExceptions());

            throw new DependencyResolutionException(
                    result, "Could not collect dependencies for project " + project.getId(), e);
        }

        depRequest.setRoot(node);

        if (logger.isWarnEnabled()) {
            for (DependencyNode child : node.getChildren()) {
                if (!child.getRelocations().isEmpty()) {
                    org.eclipse.aether.artifact.Artifact artifact =
                            child.getDependency().getArtifact();
                    String message = artifact instanceof RelocatedArtifact relocated ? relocated.getMessage() : null;
                    logger.warn("The artifact " + child.getRelocations().get(0) + " has been relocated to " + artifact
                            + (message != null ? ": " + message : ""));
                }
            }
        }

        if (logger.isDebugEnabled()) {
            node.accept(new DependencyGraphDumper(logger::debug));
        }

        try {
            process(result, repoSystem.resolveDependencies(session, depRequest).getArtifactResults());
        } catch (org.eclipse.aether.resolution.DependencyResolutionException e) {
            process(result, e.getResult().getArtifactResults());

            throw new DependencyResolutionException(
                    result, "Could not resolve dependencies for project " + project.getId(), e);
        }

View on GitHub (pinned to e4093d4e12)

Solutions

Update the dependency declaration in the POM to the relocated coordinates shown in the warning (the part after 'has been relocated to')
Run mvn dependency:tree -Dincludes=<oldGroupId>:<oldArtifactId> to find which module still declares the old coordinates
If the old coordinate comes in transitively, add a <dependencyManagement> entry pinning the new coordinates or exclude the old one

Example fix

<!-- before -->
<dependency>
  <groupId>javax.xml.bind</groupId>
  <artifactId>jaxb-api</artifactId>
  <version>2.3.1</version>
</dependency>

<!-- after: relocated coordinates -->
<dependency>
  <groupId>jakarta.xml.bind</groupId>
  <artifactId>jakarta.xml.bind-api</artifactId>
  <version>4.0.1</version>
</dependency>

Defensive patterns

Strategy: validation

Validate before calling

// Detect relocated coordinates before Maven warns about them at build time
// Run: mvn dependency:list -DincludeGroupIds=<old> and compare against the relocation table
def relocated = ['javax.xml.bind:jaxb-api': 'jakarta.xml.bind:jakarta.xml.bind-api']
relocated.each { oldGav, newGav ->
  def out = "mvn -q dependency:list -DincludeGroupIds=${oldGav.split(':')[0]}".execute().text
  if (out.contains(oldGav)) throw new GradleException("Update $oldGav -> $newGav")
}

Prevention

Grep POMs periodically for coordinates known to be relocated (javax.xml.bind, org.javaee, old commons groupIds)
Pin modern coordinates in dependencyManagement so transitive old ones cannot reintroduce themselves
Treat relocation warnings as refactoring debt and schedule them instead of muting the logger

When it happens

Trigger: DefaultProjectDependenciesResolver.resolve() walks node.getChildren() of the collected graph; any child whose first relocation differs from its current artifact triggers the warning at WARN level. Typical artifacts: javax.xml:jaxb-api relocated to jakarta.xml.bind:jakarta.xml.bind-api, or groupId renames published by the project itself.

Common situations: Legacy dependencies whose maintainers renamed groupId/artifactId (Java EE to Jakarta moves, org.apache.commons re-groupings); transitive pulls of old coordinates after a project upgraded to the new ones elsewhere; CI log audits flagging the word 'relocated'.

Related errors

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