Skip to content
javahacks.dev
DevOps

Fix Maven Could Not Resolve Dependencies Errors in Builds

Work through why Maven cannot resolve a dependency: a wrong coordinate, a cached failure, a blocked mirror, missing credentials or a proxy.

7 min read
Summarize in AI
Flat illustration of a log with a failing line and a wrench, with the Apache Maven, Docker, JUnit5 and Gradle logos.

The build stops before it compiles anything, with a message that is long and mostly noise:

Text
[ERROR] Failed to execute goal on project shop: Could not resolve dependencies for project dev.javahacks:shop:jar:1.0.0: Could not find artifact com.acme:report-engine:jar:2.3.1 in central (https://repo.maven.apache.org/maven2) -> [Help 1]

Maven could not download a jar or a POM it needs. The message names the artifact and the repository it asked, and that is nearly the whole diagnosis. There are six causes, and the cheap way to separate them is to ask the question each one answers: are the coordinates real, is a failure cached, does a repository carry the artifact, does it accept your credentials, can you reach it and can the parent POM be found. This post walks through them in the order they usually occur, with the command that confirms each. Examples use Maven 3.9 and JDK 25.

Cause 1: the coordinates are wrong

A typo in groupId, artifactId or version, a version that was never published, or an artifact that moved. Read the message literally: com.acme:report-engine:jar:2.3.1 is the coordinate Maven looked for. Check it against the repository's own web page, or ask the repository for the file directly:

Shell
curl -I https://repo.maven.apache.org/maven2/org/slf4j/slf4j-api/2.0.17/slf4j-api-2.0.17.pom
Text
HTTP/2 200

A 404 for your coordinate means it does not exist at that address. The URL is the coordinates with dots in the group id turned into slashes. Frequent real causes:

  • The version was never released. 2.3.1 was tagged internally but not published.
  • A relocation or rename. Libraries move between group ids, as javax.* artifacts moved to jakarta.* ones; the new coordinates are in the project's release notes.
  • A property that did not resolve. ${acme.version} with the property defined in a profile that is not active leaves a literal ${acme.version} in the message.
  • A SNAPSHOT that was cleaned up. Snapshot repositories delete old builds.

To see what Maven decided your coordinates are after property substitution and inheritance, print the effective POM:

Shell
mvn -B help:effective-pom | grep -B2 -A3 'report-engine'

If the dependency is correct and the project is yours, the question moves to whether the artifact was ever deployed. For how versions are chosen when two parts of the tree disagree, see Maven dependency mediation.

Cause 2: a cached failure

Maven remembers failures. After one unsuccessful attempt it writes a marker next to the missing artifact and does not retry until an interval passes (a day by default), even if you have since fixed the problem or the artifact was published:

Shell
ls ~/.m2/repository/com/acme/report-engine/2.3.1/
Text
report-engine-2.3.1.pom.lastUpdated
resolver-status.properties

A .lastUpdated file and no .jar or .pom is the signature of a cached failure. Force a retry with -U (update snapshots and retry failed lookups):

Shell
mvn -B -U verify

If that works, the cause was cached and the real problem is gone. If it does not, delete the artifact's directory under ~/.m2 and retry. A blanket rm -rf ~/.m2/repository works and costs a full re-download, so try the targeted delete first. The same cached failure explains why a colleague's machine can build while yours cannot: they never recorded a failure while the artifact was missing.

Cause 3: the repository is not configured, or a mirror hides it

Maven resolves from Central unless told otherwise. An artifact from your company repository, from JitPack or from a vendor's repository needs that repository configured, and a mirror in settings.xml can override your configuration so that it never gets asked.

pom.xmlXML
<repositories>
  <repository>
    <id>acme</id>
    <url>https://nexus.example.test/repository/maven-releases/</url>
  </repository>
</repositories>
~/.m2/settings.xmlXML
<mirrors>
  <mirror>
    <id>corp</id>
    <mirrorOf>*</mirrorOf>
    <url>https://nexus.example.test/repository/maven-public/</url>
  </mirror>
</mirrors>

With mirrorOf set to *, every request, including those for the acme repository, goes to the mirror, and the mirror must contain the artifact. If it does not, you get the error with corp as the repository name, not central. Read which repository id appears in the message: it tells you where Maven actually looked. The effective settings, with mirrors and profiles merged, are printed by:

Shell
mvn -B help:effective-settings

A mirror that should exclude a repository uses *,!acme. The behavior is documented in the mirror and repository guide, and a full private-repository setup is in setting up a private Maven repository.

Cause 4: credentials

A private repository answers an anonymous request with 401 Unauthorized or 403 Forbidden, which Maven reports inside the same error:

Text
Could not transfer artifact com.acme:report-engine:pom:2.3.1 from/to acme (https://nexus.example.test/repository/maven-releases/): status code: 401, reason phrase: Unauthorized (401)

The message now says Could not transfer, not Could not find: the repository exists and refused you. Credentials live in settings.xml, keyed by the repository id, and the id must match exactly:

~/.m2/settings.xmlXML
<servers>
  <server>
    <id>acme</id>
    <username>${env.NEXUS_USER}</username>
    <password>${env.NEXUS_PASSWORD}</password>
  </server>
</servers>

A 404 from a private repository for an artifact that exists is sometimes a permission problem disguised: some servers return 404 instead of 403 to hide the existence of what you may not read. Test with the same credentials in a browser or with curl -u. In CI, make sure the variables are set in the job and are not blank (a secret not exposed to pull requests from forks is the usual surprise), and never write the password into the POM. The settings file reference is at maven.apache.org/settings.html.

Cause 5: network, proxy or certificates

If Maven cannot reach the repository at all, the message differs again:

Text
Could not transfer artifact ... from/to central: Connect to repo.maven.apache.org:443 failed: connect timed out

Work outward from the machine. Is there a proxy? Corporate networks need one, configured in settings.xml:

~/.m2/settings.xmlXML
<proxies>
  <proxy>
    <id>corp</id>
    <active>true</active>
    <protocol>https</protocol>
    <host>proxy.example.test</host>
    <port>3128</port>
    <nonProxyHosts>localhost|*.example.test</nonProxyHosts>
  </proxy>
</proxies>

Check DNS and reachability with curl -v https://repo.maven.apache.org/maven2/. A TLS inspection proxy replaces the server certificate with its own, and the JVM does not trust the signer, which gives a different failure entirely: PKIX path building failed. That has its own post, fixing PKIX path building failed, with the truststore steps. Also check the clock: a machine with the wrong date fails certificate validation. Finally, a flaky network can cause a partial download; retry once with -U before suspecting anything else.

Cause 6: the parent POM

When the artifact named in the error is a pom and not a jar, and especially when it is a -parent or -bom, the failure is in inheritance or imports. Maven needs the parent to understand the project at all:

Text
Non-resolvable parent POM for dev.javahacks:shop:1.0.0: Could not find artifact dev.javahacks:shop-parent:pom:2.0.0 and 'parent.relativePath' points at wrong local POM

Maven first looks for the parent at ../pom.xml (the default relativePath), then in the repositories. If the parent lives elsewhere, or only in the repository, say so:

pom.xmlXML
<parent>
  <groupId>dev.javahacks</groupId>
  <artifactId>shop-parent</artifactId>
  <version>2.0.0</version>
  <relativePath/>      <!-- empty: do not look on disk, use the repository -->
</parent>

If the parent is part of the same multi-module build, build from the root so it is found; building a child alone with a parent that has never been installed fails. mvn -pl shop-service -am verify builds the child and what it needs. The same applies to a BOM imported with <scope>import</scope>. The structure of POMs and the order of resolution are in the Maven tutorial on the POM and packaging.

A decision table

Message saysLikely causeFirst move
Could not find artifact in centralWrong coordinates, or repository not configuredcurl -I the URL
.lastUpdated file presentCached failuremvn -U
Could not transfer ... 401/403CredentialsCheck settings.xml server id
Connect ... timed outNetwork or proxycurl -v the repository
PKIX path building failedUntrusted certificateImport the CA into the truststore
Non-resolvable parent POMParent path or installFix relativePath, build from root

Where this does not apply

If the error is a compilation failure after resolution succeeded, the dependency resolved and something else is wrong. If Maven resolves a dependency but you see a different version than expected, that is mediation and not a missing artifact. And in an offline build (-o), anything not already in the local repository fails by design; remove -o or pre-populate with mvn dependency:go-offline.

Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.