The Maven error "Failed to read artifact descriptor" means Maven could not download or parse the POM file for a dependency. The fix depends on the root cause: a corrupted local cache, wrong dependency coordinates, network or proxy problems, or a misconfigured repository. In most cases, purging the local repository entry for the failing artifact and re-running the build resolves it immediately.

What the Error Actually Means

When Maven resolves a dependency, it first downloads the artifact's POM file (the descriptor) from a remote repository, then uses that POM to resolve transitive dependencies. The "Failed to read artifact descriptor" error fires when Maven either cannot fetch this POM or cannot parse it after downloading.

A typical stack trace looks like this:

1[ERROR] Failed to execute goal on project my-app:
2  Could not resolve dependencies for project com.example:my-app:jar:1.0:
3  Failed to read artifact descriptor for
4  org.apache.commons:commons-lang3:jar:3.12.0:
5  Could not transfer artifact org.apache.commons:commons-lang3:pom:3.12.0
6  from/to central (https://repo.maven.apache.org/maven2):
7  Connection timed out

The last line is the actual cause. In this example it is a network timeout, but the cause varies.

Root Causes and Targeted Fixes

1. Corrupted Local Repository Cache

Maven caches everything it downloads under ~/.m2/repository. If a previous download was interrupted, the cached POM may be truncated or contain an HTTP error page instead of XML. Maven will keep trying to read the corrupted file instead of re-downloading.

1# Delete the specific artifact's local cache
2rm -rf ~/.m2/repository/org/apache/commons/commons-lang3/3.12.0
3
4# Re-run the build
5mvn clean install

For a broader cleanup:

# Purge all locally cached metadata and re-resolve
mvn dependency:purge-local-repository

2. Wrong Dependency Coordinates

A typo in groupId, artifactId, or version causes Maven to look for an artifact that does not exist. Maven treats "not found" the same as "failed to read."

1<!-- Wrong: typo in groupId -->
2<dependency>
3    <groupId>org.apache.common</groupId>  <!-- should be "commons" -->
4    <artifactId>commons-lang3</artifactId>
5    <version>3.12.0</version>
6</dependency>
7
8<!-- Correct -->
9<dependency>
10    <groupId>org.apache.commons</groupId>
11    <artifactId>commons-lang3</artifactId>
12    <version>3.12.0</version>
13</dependency>

Verify coordinates by searching on Maven Central before assuming a network issue.

3. Network or Proxy Problems

If your machine cannot reach the remote repository, Maven cannot download the descriptor. This shows up as connection timeouts or SSL handshake failures.

1# Test connectivity to Maven Central
2curl -I https://repo.maven.apache.org/maven2/
3
4# If behind a proxy, configure it in ~/.m2/settings.xml

1<!-- ~/.m2/settings.xml proxy configuration -->
2<settings>
3  <proxies>
4    <proxy>
5      <id>company-proxy</id>
6      <active>true</active>
7      <protocol>https</protocol>
8      <host>proxy.example.com</host>
9      <port>8080</port>
10      <username>proxyuser</username>
11      <password>proxypass</password>
12    </proxy>
13  </proxies>
14</settings>

4. Missing or Misconfigured Repository

If the artifact lives in a private or third-party repository (not Maven Central), that repository must be declared in the POM or settings.xml.

1<!-- pom.xml: declare a custom repository -->
2<repositories>
3    <repository>
4        <id>jitpack</id>
5        <url>https://jitpack.io</url>
6    </repository>
7</repositories>

1<!-- settings.xml: mirror configuration for corporate Nexus/Artifactory -->
2<settings>
3  <mirrors>
4    <mirror>
5      <id>nexus</id>
6      <mirrorOf>*</mirrorOf>
7      <url>https://nexus.internal.example.com/repository/maven-public/</url>
8    </mirror>
9  </mirrors>
10</settings>

A mirrorOf set to * redirects all repository requests through the mirror. If that mirror is down or misconfigured, every artifact resolution will fail.

5. Maven _remote.repositories Marker Files

Maven creates .lastUpdated and _remote.repositories marker files in the local cache. Sometimes these markers tell Maven "this artifact does not exist on any repository," preventing it from re-trying the download even after the underlying issue is fixed.

1# Find and remove marker files for a specific artifact
2find ~/.m2/repository/org/apache/commons/commons-lang3 \
3  -name "*.lastUpdated" -delete
4
5find ~/.m2/repository/org/apache/commons/commons-lang3 \
6  -name "_remote.repositories" -delete

Then re-run the build. Maven will attempt a fresh download.

Diagnostic Commands

Before trying fixes at random, run these commands to understand what Maven is actually doing:

1# Debug mode: shows every repository Maven contacts and every file it tries to read
2mvn clean install -X 2>&1 | grep -i "artifact\|download\|failed"
3
4# Dependency tree: shows where the failing artifact is required
5mvn dependency:tree
6
7# Effective POM: shows the fully resolved POM including inherited repositories
8mvn help:effective-pom
9
10# Effective settings: shows the resolved settings.xml (useful for proxy/mirror issues)
11mvn help:effective-settings

Troubleshooting Decision Table

Common Pitfalls

• Running mvn dependency:purge-local-repository without the -DactTransitively=false flag. By default it also purges transitive dependencies, which can be slow and unnecessary.
• Ignoring the actual error message at the bottom of the stack trace. The "Failed to read artifact descriptor" line is the symptom; the cause is always further down (timeout, 404, SSL error, parse error).
• Adding random repositories to the POM hoping one will have the artifact. Each additional repository slows builds and can introduce security risks.
• Forgetting that Maven caches "not found" results. If you fixed the underlying issue (added a repository, fixed coordinates), you still need to delete the .lastUpdated files or the cached entry.
• Using -U (force update snapshots) and assuming it also re-downloads corrupted release artifacts. The -U flag only affects SNAPSHOT metadata.

Summary

• "Failed to read artifact descriptor" is a symptom, not a root cause. Always read the full error message to identify the actual failure (network, 404, corruption, parse error).
• The most common fix is deleting the corrupted local cache entry under ~/.m2/repository and re-running the build.
• Verify dependency coordinates against Maven Central before investigating network issues.
• For proxy or mirror problems, inspect settings.xml and test connectivity with curl.
• Use mvn clean install -X for detailed diagnostic output, and mvn dependency:tree to understand where the failing artifact is required.