Fix: Maven Could Not Resolve Dependencies - Failed to Read Artifact Descriptor

The Error

You run mvn clean install or mvn package and the build fails with:

[ERROR] Failed to execute goal on project my-app:
Could not resolve dependencies for project com.example:my-app:jar:1.0.0:
Failed to read artifact descriptor for org.springframework:spring-core:jar:6.1.4:
Could not transfer artifact org.springframework:spring-core:pom:6.1.4
from/to central (https://repo.maven.apache.org/maven2):
Transfer failed for https://repo.maven.apache.org/maven2/org/springframework/spring-core/6.1.4/spring-core-6.1.4.pom

Or a variation like:

[ERROR] Failed to execute goal on project my-app:
Could not resolve dependencies for project com.example:my-app:jar:1.0.0:
The following artifacts could not be resolved:
  org.some.library:some-artifact:jar:2.3.1 (absent):
  Could not find artifact org.some.library:some-artifact:jar:2.3.1 in central
    (https://repo.maven.apache.org/maven2)

Or sometimes:

[ERROR] Non-resolvable parent POM for com.example:my-module:1.0.0:
Could not transfer artifact com.example:parent-pom:pom:1.0.0
from/to internal-repo (https://nexus.company.com/repository/maven-public/):
Authentication failed for https://nexus.company.com/repository/maven-public/

The build stops and nothing compiles. Every dependency-related task fails until you fix the underlying cause.

Why This Happens

Maven resolves dependencies by downloading JAR and POM files from remote repositories into your local cache (~/.m2/repository). The “Could not resolve dependencies” error means Maven tried to fetch or read an artifact and failed.

There are several root causes:

• Corrupted local cache: A previous download was interrupted, leaving broken JAR or POM files in ~/.m2/repository. Maven sees the file exists and tries to read it, but the content is garbage.
• Network or proxy issues: You are behind a corporate firewall or HTTP proxy, and Maven cannot reach Maven Central or your internal repository.
• Wrong mirror or repository configuration: Your settings.xml points to a mirror that is down, misconfigured, or requires authentication you have not provided.
• The artifact does not exist: The dependency version you specified was never published. A typo in the groupId, artifactId, or version is enough.
• Parent POM not available: Your project inherits from a parent POM that Maven cannot find, either because it is not in the repo or not installed locally.
• Version conflicts: Two dependencies pull in incompatible versions of the same transitive dependency, and Maven cannot reconcile them.
• Repository policy blocks snapshots or releases: The repository configuration only allows releases, but you are requesting a SNAPSHOT version (or vice versa).

Each cause has a different fix. Work through them in order; most dependency resolution failures fall into the first three categories.

Fix 1: Force Update Dependencies with the -U Flag

Maven caches download failures. If an artifact failed to download once, Maven marks it as “not found” and will not retry for a set period (usually daily). The -U flag forces Maven to check remote repositories again:

mvn clean install -U

This tells Maven to update snapshots and release policies, ignoring the cached failure markers. If the issue was a temporary network blip or a repository that was briefly unavailable, this single flag resolves it.

Note: The -U flag only forces re-checking remote repositories. It does not fix corrupted files already in your local cache. If the problem persists after -U, move to Fix 2.

Fix 2: Clear Corrupted Local Repository Cache

A corrupted ~/.m2/repository is the most common cause. Partial downloads, interrupted builds, or disk errors leave behind broken files that Maven cannot parse.

Delete the Specific Artifact

Find the problem artifact from the error message and delete its folder. For example, if the error mentions org.springframework:spring-core:6.1.4:

rm -rf ~/.m2/repository/org/springframework/spring-core/6.1.4

Then rebuild:

mvn clean install

Maven re-downloads the artifact from scratch.

Delete the Entire Dependency Cache

If multiple artifacts are corrupted or you are unsure which ones are broken, nuke the entire local repository:

rm -rf ~/.m2/repository

Then rebuild. Maven re-downloads everything. This takes longer but guarantees a clean state.

Pro Tip: Before deleting the whole ~/.m2/repository, check its size. On large projects it can be several gigabytes. If you are on a slow connection, delete only the affected artifact folders first. You can also look for files ending in .lastUpdated inside ~/.m2/repository - these are failure markers from previous download attempts. Deleting them has the same effect as -U but is more targeted: find ~/.m2/repository -name "*.lastUpdated" -delete

Check for _remote.repositories Files

Maven stores metadata about where each artifact was downloaded from in _remote.repositories files. If you switch between repositories (for example, from a corporate Nexus to Maven Central), these files can cause conflicts. Delete them alongside the artifact:

find ~/.m2/repository -name "_remote.repositories" -delete

Fix 3: Fix Your settings.xml Configuration

Maven reads configuration from two locations:

• Global: ${MAVEN_HOME}/conf/settings.xml
• User: ~/.m2/settings.xml

User settings override global settings. Misconfigurations here cause most corporate environment failures.

Locate Your Active settings.xml

Check which settings file Maven is actually using:

mvn help:effective-settings

This prints the merged result of all settings files. Look for unexpected mirrors, proxies, or servers.

Fix Mirror Configuration

A mirror intercepts all requests to a given repository and redirects them. If your mirror is down or misconfigured, every dependency resolution fails.

A correct mirror configuration in ~/.m2/settings.xml looks like:

<settings>
  <mirrors>
    <mirror>
      <id>company-mirror</id>
      <name>Company Nexus</name>
      <url>https://nexus.company.com/repository/maven-public/</url>
      <mirrorOf>central</mirrorOf>
    </mirror>
  </mirrors>
</settings>

Common issues:

• mirrorOf set to *: This redirects all repository requests through the mirror, including any custom repositories defined in your pom.xml. If the mirror does not proxy those repositories, the artifacts will not be found. Change * to central or a specific list.
• Wrong URL: Verify the mirror URL by opening it in a browser. You should see a repository index or at least get a response from the server.
• Missing authentication: If the mirror requires credentials, add a <server> block (see below).

Fix Server Authentication

If your repository requires authentication, you need a matching <server> entry where the <id> matches the repository or mirror <id>:

<settings>
  <servers>
    <server>
      <id>company-mirror</id>
      <username>your-username</username>
      <password>your-password</password>
    </server>
  </servers>
</settings>

Note: Storing passwords in plain text is a security risk. Use Maven’s password encryption to encrypt credentials in settings-security.xml.

Fix 4: Configure Proxy Settings for Corporate Networks

Behind a corporate proxy, Maven cannot reach Maven Central unless you explicitly configure the proxy. This is a frequent issue in enterprise environments and the error often looks like a timeout or connection refused. If you are also seeing SSL-related errors behind a proxy, check out how to fix SSL certificate problems which covers certificate trust issues in detail.

Add this to your ~/.m2/settings.xml:

<settings>
  <proxies>
    <proxy>
      <id>company-proxy</id>
      <active>true</active>
      <protocol>https</protocol>
      <host>proxy.company.com</host>
      <port>8080</port>
      <username>proxyuser</username>
      <password>proxypassword</password>
      <nonProxyHosts>localhost|127.0.0.1|*.company.com</nonProxyHosts>
    </proxy>
  </proxies>
</settings>

Key details:

• Set protocol to https if Maven Central (or your mirror) uses HTTPS. You may need a second <proxy> block for http if some repos use plain HTTP.
• nonProxyHosts excludes internal hosts from the proxy. Use | as a separator and * for wildcards. Always include your internal repository hostname here.
• If your proxy does not require authentication, omit the <username> and <password> fields.

You can verify your proxy is working by running Maven with debug output:

mvn clean install -X

Look for lines mentioning “proxy” in the output. Maven logs which proxy it uses for each connection.

Fix 5: Add Missing Repositories to Your pom.xml

If the artifact is not on Maven Central, you need to tell Maven where to find it. Some libraries are hosted on custom repositories (JBoss, Spring Milestones, Atlassian, etc.).

Add the repository to your pom.xml:

<repositories>
  <repository>
    <id>spring-milestones</id>
    <name>Spring Milestones</name>
    <url>https://repo.spring.io/milestone</url>
    <snapshots>
      <enabled>false</enabled>
    </snapshots>
  </repository>
</repositories>

If the artifact is a Maven plugin, use <pluginRepositories> instead:

<pluginRepositories>
  <pluginRepository>
    <id>spring-milestones</id>
    <url>https://repo.spring.io/milestone</url>
  </pluginRepository>
</pluginRepositories>

Common Mistake: Adding a repository in pom.xml while having a <mirrorOf>*</mirrorOf> in your settings.xml. The mirror intercepts the custom repository request and tries to find the artifact in the mirror, which does not have it. Either change the mirror’s mirrorOf to central or add the custom repository to your mirror’s proxy group (in Nexus/Artifactory).

Fix 6: Fix Dependency Version Conflicts

When two dependencies pull in different versions of the same transitive dependency, Maven uses its “nearest definition” strategy. This can silently select the wrong version, leading to resolution failures or runtime errors like ClassNotFoundException.

Analyze the Dependency Tree

Use mvn dependency:tree to see exactly what Maven resolved:

mvn dependency:tree -Dincludes=org.springframework:spring-core

The -Dincludes filter shows only the dependency you care about. The output looks like:

[INFO] com.example:my-app:jar:1.0.0
[INFO] +- org.springframework:spring-webmvc:jar:6.1.4:compile
[INFO] |  \- org.springframework:spring-core:jar:6.1.4:compile
[INFO] \- org.some.library:old-spring-lib:jar:1.0.0:compile
[INFO]    \- org.springframework:spring-core:jar:5.3.30:compile (omitted for conflict)

The (omitted for conflict) marker shows where Maven dropped a version.

Force a Specific Version

If Maven is picking the wrong version, explicitly declare the version you need in your pom.xml’s <dependencyManagement> section:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>spring-core</artifactId>
      <version>6.1.4</version>
    </dependency>
  </dependencies>
</dependencyManagement>

This forces all transitive references to use version 6.1.4, regardless of what individual dependencies request.

Exclude Conflicting Transitive Dependencies

Alternatively, exclude the problematic transitive dependency from the library that pulls it in:

<dependency>
  <groupId>org.some.library</groupId>
  <artifactId>old-spring-lib</artifactId>
  <version>1.0.0</version>
  <exclusions>
    <exclusion>
      <groupId>org.springframework</groupId>
      <artifactId>spring-core</artifactId>
    </exclusion>
  </exclusions>
</dependency>

This prevents the old version from being pulled in at all.

Fix 7: Resolve Parent POM Issues

If your project uses a parent POM that Maven cannot find, you get errors like:

[ERROR] Non-resolvable parent POM for com.example:my-module:1.0.0:
Could not find artifact com.example:parent-pom:pom:1.0.0

Install the Parent POM Locally

If the parent POM is part of your project (a multi-module build), install it first:

cd parent-project
mvn clean install -N

The -N flag (non-recursive) installs only the parent POM without building child modules. Then go back to your module and build again.

Check relativePath

In a multi-module project, Maven looks for the parent POM relative to the child module. If the directory structure does not match the default (../pom.xml), specify the correct path:

<parent>
  <groupId>com.example</groupId>
  <artifactId>parent-pom</artifactId>
  <version>1.0.0</version>
  <relativePath>../../parent/pom.xml</relativePath>
</parent>

If the parent is only available from a remote repository (not on the filesystem), set <relativePath/> to an empty value. This tells Maven to skip the local filesystem lookup and go straight to the repository:

<parent>
  <groupId>com.example</groupId>
  <artifactId>parent-pom</artifactId>
  <version>1.0.0</version>
  <relativePath/>
</parent>

Fix 8: Check for Typos and Non-Existent Versions

This sounds basic, but it catches people more often than you would expect. A single wrong character in groupId, artifactId, or version causes a resolution failure.

Verify your dependency coordinates:

1. Go to Maven Central Search or mvnrepository.com.
2. Search for the artifact.
3. Confirm the exact groupId, artifactId, and available versions.

Watch for these common traps:

• Old group IDs: Some libraries changed their groupId over time. For example, javax.servlet became jakarta.servlet after Jakarta EE took over. If you are using a newer version with the old group ID, it will not resolve.
• Classifier issues: Some artifacts require a classifier like jdk8 or linux-x86_64. Without the correct classifier, Maven cannot find the file.
• Wrong packaging type: If you need a pom type (like a BOM) but left it as the default jar, resolution may fail.

Fix 9: Handle SNAPSHOT Resolution Failures

SNAPSHOT versions have special resolution rules. Maven checks for new SNAPSHOT versions periodically (configurable, defaults to daily). If the SNAPSHOT is not available or the repository does not allow snapshots, resolution fails.

Make sure the repository has snapshots enabled:

<repository>
  <id>snapshots-repo</id>
  <url>https://nexus.company.com/repository/maven-snapshots/</url>
  <releases>
    <enabled>false</enabled>
  </releases>
  <snapshots>
    <enabled>true</enabled>
    <updatePolicy>always</updatePolicy>
  </snapshots>
</repository>

The <updatePolicy>always</updatePolicy> setting tells Maven to check for new snapshot versions on every build. Other options are daily (default), interval:X (minutes), and never.

Fix 10: Run Maven in Debug Mode

When none of the above fixes work, run Maven with the -X flag for full debug output:

mvn clean install -X 2>&1 | tee maven-debug.log

This produces a lot of output. Search for these key terms in the log:

• “Could not transfer”: Shows the exact URL Maven tried and the HTTP error code.
• “Authentication”: Reveals whether credentials were sent and accepted.
• “Using mirror”: Shows which mirror Maven is routing requests through.
• “Proxy”: Confirms whether proxy settings are active.

You can also use the Maven dependency plugin to get more insight:

mvn dependency:resolve -X

This focuses the debug output on dependency resolution specifically, cutting out most of the build noise.

For complex multi-module projects, the effective POM is also valuable:

mvn help:effective-pom

This shows the fully merged POM after all parent inheritance and profile activation. Check that repositories, mirrors, and dependency versions look correct in the output.

Fix 11: Check Java and Maven Version Compatibility

Certain dependency versions require specific Java versions. If you are running Java 8 but a dependency was compiled for Java 17, Maven may fail to read its descriptor.

Check your Java and Maven versions:

java -version
mvn --version

Make sure the Java version listed by mvn --version matches what you expect. Maven uses the JAVA_HOME environment variable. If JAVA_HOME points to a different JDK than what is on your PATH, you can get confusing errors.

If you are also running into memory issues during large builds, you may need to increase Maven’s heap size, which follows the same JVM tuning principles.

Fix 12: Verify Repository Accessibility

Sometimes the repository itself is down or unreachable. Test connectivity directly:

curl -I https://repo.maven.apache.org/maven2/

You should get a 200 OK response. If you get a timeout, connection refused, or SSL error, the issue is network-level, not Maven-specific. See how to debug connection failures for troubleshooting network-level issues.

For internal repositories, check:

• Is the Nexus/Artifactory server running?
• Is the repository URL correct (check for trailing slashes, typos)?
• Have your credentials expired?
• Is the server’s SSL certificate valid and trusted by your JVM?

You can test artifact availability by constructing the direct URL. For org.springframework:spring-core:6.1.4, the URL is:

https://repo.maven.apache.org/maven2/org/springframework/spring-core/6.1.4/spring-core-6.1.4.pom

Open it in a browser. If you can see the POM XML, Maven Central has the artifact and the problem is on your end.

Still Not Working?

If you have tried everything above and Maven still cannot resolve dependencies, check these less obvious causes:

• Maven wrapper version mismatch: If the project uses mvnw, check .mvn/wrapper/maven-wrapper.properties. The wrapper may be downloading an old Maven version that has known bugs. Update it with mvn wrapper:wrapper -Dmaven=3.9.6.
• OS-level DNS issues: Maven relies on DNS to resolve repository hostnames. Try nslookup repo.maven.apache.org to verify DNS resolution works. Corporate VPNs sometimes interfere with DNS.
• Disk space: Maven cannot write downloaded artifacts if the disk is full. Check available space on the partition where ~/.m2/repository lives.
• File permissions: On Linux/macOS, check that your user owns the ~/.m2 directory. A sudo mvn install in the past may have created files owned by root. Fix with sudo chown -R $(whoami) ~/.m2.
• Antivirus or firewall interference: Some security software intercepts HTTPS connections and modifies certificates, causing SSL handshake failures. Try temporarily disabling your antivirus to test.
• Maven daemon (mvnd) cache: If you use mvnd, it keeps a long-running daemon process that caches state. Restart it with mvnd --stop before retrying.
• Gradle alternative: If you are migrating between build tools, dependency coordinates may differ. Check Gradle build failures for the Gradle-specific equivalent of these issues.

As a last resort, create a minimal pom.xml with just the failing dependency and try to build it in isolation. If it works, the problem is somewhere in your project’s dependency tree or settings inheritance. If it fails, the problem is environmental (network, proxy, JVM, or cache).