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.

The build stops before it compiles anything, with a message that is long and mostly noise:
[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:
curl -I https://repo.maven.apache.org/maven2/org/slf4j/slf4j-api/2.0.17/slf4j-api-2.0.17.pomHTTP/2 200A 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.1was tagged internally but not published. - A relocation or rename. Libraries move between group ids, as
javax.*artifacts moved tojakarta.*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:
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:
ls ~/.m2/repository/com/acme/report-engine/2.3.1/report-engine-2.3.1.pom.lastUpdated
resolver-status.propertiesA .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):
mvn -B -U verifyIf 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.
<repositories>
<repository>
<id>acme</id>
<url>https://nexus.example.test/repository/maven-releases/</url>
</repository>
</repositories><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:
mvn -B help:effective-settingsA 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:
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:
<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:
Could not transfer artifact ... from/to central: Connect to repo.maven.apache.org:443 failed: connect timed outWork outward from the machine. Is there a proxy? Corporate networks need one, configured in settings.xml:
<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:
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 POMMaven 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:
<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 says | Likely cause | First move |
|---|---|---|
Could not find artifact in central | Wrong coordinates, or repository not configured | curl -I the URL |
.lastUpdated file present | Cached failure | mvn -U |
Could not transfer ... 401/403 | Credentials | Check settings.xml server id |
Connect ... timed out | Network or proxy | curl -v the repository |
PKIX path building failed | Untrusted certificate | Import the CA into the truststore |
Non-resolvable parent POM | Parent path or install | Fix 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.


