Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Maven: Could not resolve dependencies, was cached in the local repository

Maven caches failed resolutions in .lastUpdated markers. Force an update, declare the missing repository, and read the status code before purging.

~5 min readJava
#Maven#Java#CI#Build
A maven dependency crate stalled at a cyan local repository gate, amber last updated marker and forced update key

Introduction & Quick Summary

text
[ERROR] Failed to execute goal on project app: Could not resolve dependencies for project com.example:app:jar:1.0.0: The following artifacts could not be resolved: org.example:shared:jar:2.1.0 (absent): org.example:shared:jar:2.1.0 was not found in https://repo.maven.apache.org/maven2 during the period ... was cached in the local repository, resolution will not be reattempted until the update interval of central has elapsed or updates are forced

Two failures share this message: the artifact may be missing, or Maven cached a failure and will not retry until the update interval expires. The second is far more common after a repository is added or a proxy is fixed.

The four causes:

  • A cached failure. Maven writes *.lastUpdated markers next to the missing artifact, and will not re-request until the interval passes or -U is used.
  • The repository is not declared. A settings.xml mirror, a <repository> in a parent POM, or a corporate proxy that only allows central.
  • The artifact really does not exist. A wrong group or version, a snapshot that was never deployed, or a classifier mismatch.
  • Offline or a broken local repo. -o, a partially downloaded JAR, or a _remote.repositories file that ties the artifact to a repository that no longer exists.
Message fragmentMeaningFirst fix
was cached in the local repositoryFailure marker presentmvn -U, or delete *.lastUpdated
Could not find artifact ... in centralNot published to centralDeclare the right repository
(absent)Resolver knows the coordinate but has no fileCheck the version exists
Could not transfer artifact ... 401Credentials for a private repositorysettings.xml server entry
was cached ... in offline mode-o is setRemove -o

Core Mechanics, Signatures & Reproducible Setup

Maven resolves a dependency by trying each configured repository in order, then writing the artifact to ~/.m2/repository/<group path>/<artifact>/<version>/. On failure it writes <artifact>-<version>.jar.lastUpdated with the repository id and timestamp. That file is the cache of the failure, and it is why the same error returns instantly on the next build.

A reproduction is one POM with a coordinate that does not exist:

xml
<project> <modelVersion>4.0.0</modelVersion> <groupId>com.example</groupId> <artifactId>app</artifactId> <version>1.0.0</version> <dependencies> <dependency> <groupId>org.example</groupId> <artifactId>shared</artifactId> <version>2.1.0</version> </dependency> </dependencies> </project>
bash
mvn -q dependency:resolve ls ~/.m2/repository/org/example/shared/2.1.0/ # shared-2.1.0.jar.lastUpdated
bash
# after the artifact is published or the repository is added mvn -U dependency:resolve ls ~/.m2/repository/org/example/shared/2.1.0/ # shared-2.1.0.jar shared-2.1.0.pom _remote.repositories

-U forces a re-check of releases and snapshots once. It does not fix a coordinate that does not exist.

Key Comparison Table

The recovery flags differ in how much they throw away, and choosing the biggest one for a one-artifact problem wastes a full download.

CommandClears failure markersRe-downloadsScopeTypical use
mvn -UYes, once per buildMissing and snapshot artifactsWhole buildAdded a repository
rm ~/.m2/.../*.lastUpdatedYes, for that artifactThat artifactOne coordinateStuck single dependency
mvn -U dependency:purge-local-repositoryYesAll project dependenciesProjectCorrupt local repo
mvn -oNo, disables networkNothingWhole buildOffline, already populated
mvn -llr (legacy)Yes, ignores _remote.repositoriesAs neededWhole buildMaven 3.0 local repo layout
mvn -Dmaven.repo.local=/tmp/m2Yes, fresh repositoryEverythingWhole buildIsolating a corruption

The local repository records which repository an artifact came from, which decides whether a resolution succeeds when that repository is gone.

File in the version directoryMeansEffect when the repository disappears
_remote.repositoriesArtifact resolved from these reposResolution fails unless -llr is used
*.lastUpdatedLast failed attempt and its timestampResolution is skipped until the interval
.part fileInterrupted downloadCorrupt artifact, resolution fails

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

Force one artifact without purging everything

The narrow fix is to delete the failure markers for the coordinate and resolve again, which is fast in a large multi-module build.

bash
find ~/.m2/repository/org/example/shared -name '*.lastUpdated' -delete mvn -q -pl app dependency:resolve
bash
# inspect what the marker says before deleting it cat ~/.m2/repository/org/example/shared/2.1.0/*.lastUpdated # #NOTE: This is a Maven Resolver internal implementation file... # https://repo.maven.apache.org/maven2/.error= # https://repo.maven.apache.org/maven2/.lastUpdated=20261122071000

The error= line is the HTTP status the repository returned, which distinguishes a 404 from a 401.

Declare the repository the artifact actually lives in

A dependency from JitPack, GitHub Packages, or an internal Nexus is not in Maven Central, and Maven will not guess. The repository must be in the POM or in settings.xml, and the id must match the one a mirror or server entry uses.

xml
<repositories> <repository> <id>company-nexus</id> <url>https://nexus.example.com/repository/maven-releases/</url> <releases><enabled>true</enabled></releases> <snapshots><enabled>false</enabled></snapshots> </repository> </repositories>
xml
<!-- ~/.m2/settings.xml --> <settings> <servers> <server> <id>company-nexus</id> <username>${env.NEXUS_USER}</username> <password>${env.NEXUS_PASSWORD}</password> </server> </servers> <mirrors> <mirror> <id>company-nexus</id> <mirrorOf>central</mirrorOf> <url>https://nexus.example.com/repository/maven-public/</url> </mirror> </mirrors> </settings>

A mirror with <mirrorOf>*</mirrorOf> routes every repository, including one the build needs, through a single host. That is a frequent cause of Could not find artifact in CI when the mirror lacks a proxy rule.

Snapshots and the update policy

Snapshots are cached with an update interval, so a freshly deployed snapshot is invisible until the interval passes or -U is used. A CI job that must see the latest snapshot should always pass -U for that module.

xml
<repository> <id>snapshots</id> <url>https://nexus.example.com/repository/maven-snapshots/</url> <snapshots> <enabled>true</enabled> <updatePolicy>always</updatePolicy> <checksumPolicy>warn</checksumPolicy> </snapshots> </repository>
bash
mvn -U -pl service -am install -DskipTests

-am builds the required modules from the reactor, which is usually better than pulling a half-published snapshot from a repository.

Multi-module reactors and the install step

A module that depends on a sibling's current version fails when the sibling is not installed and the reactor does not include it. The artifact exists in the source tree but not in the local repository.

bash
# build the dependency chain mvn -pl app -am dependency:resolve # or install the parent and siblings first mvn -q -DskipTests install

Using ${project.version} for sibling dependencies, plus -am, keeps the reactor consistent without hand-editing versions.

Credentials, proxies and TLS

A 401, a 404, and a proxy that intercepts TLS all surface as Could not resolve dependencies, so the status line in the error output is the decisive evidence.

bash
# show the underlying transfer errors mvn -U -e -X dependency:resolve 2>&1 | grep -iE "HTTP|401|403|404|handshake|protocol" | head -20
xml
<proxy> <id>corp-proxy</id> <active>true</active> <protocol>https</protocol> <host>proxy.example.com</host> <port>8080</port> <nonProxyHosts>localhost|*.internal</nonProxyHosts> </proxy>

An old JDK that cannot negotiate TLS 1.2 produces Received fatal alert: protocol_version, which no repository configuration can fix; upgrading the JDK does.

Common Compilation/Runtime Mistakes & Version Gotchas

Running mvn clean install again. Clean removes target/, not the failure markers in ~/.m2, so the same cached failure returns.

Purging the whole local repository. rm -rf ~/.m2/repository fixes the problem and costs a full download of every dependency; delete the specific coordinate's markers instead.

Mixing -o with a dependency that is not cached. Offline mode reports the artifact as absent even when the repository has it. Read the in offline mode fragment before debugging the network.

Assuming a mirror and a repository are interchangeable. A mirror redirects an existing repository id; a repository adds a source. A build that needs both requires both.

Leaving -U in every build. It defeats the update interval and makes every build contact every repository. Use it when a dependency changed, not as a permanent flag.

Version notes. Maven 3.0's -llr flag was removed in later 3.x releases, so a script copied from an old guide fails on the option. Maven 3.9 changed how it warns about HTTP repositories, and Maven 4 defaults to blocking plain HTTP; both surface as resolution failures rather than warnings in strict builds. The _remote.repositories file has been written since Maven 3.0, so a lockfile-style local repository copied between machines can block resolution for artifacts that are present.

Order of work: read the failing coordinate and the repository URL from the error, -U once, then check whether the artifact exists in that repository at all. A direct request settles it fastest: fetch the POM with the curl builder, and compare the published SHA-1 against the local file with the hash tool when a checksum is the suspect.

Official references: Maven CLI options and Maven settings reference.

Official references

primary documentation

The Java documentation that defines the behaviour this guide explains.

Try matching browser tools

All tools

Small utilities that fit Java work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Java guides

More in Java

All Java guides

The guides filed next to this one in Java, in library order.