Introduction

Failed to read artifact descriptor in IntelliJ usually means Maven could not resolve a dependency's pom.xml from the configured repositories. IntelliJ is often just where the problem becomes visible; the underlying issue is normally wrong coordinates, missing repository access, bad credentials, or a corrupted local Maven cache.

What an Artifact Descriptor Is

Maven does not only download jar files. It also resolves the artifact descriptor, which is typically the dependency's own pom.xml. That descriptor tells Maven about:

• transitive dependencies
• packaging metadata
• parent POM information
• version and repository relationships

If Maven cannot fetch or parse that descriptor, dependency resolution stops and IntelliJ reports the error.

Start with the Dependency Coordinates

The fastest failure mode is simply a wrong groupId, artifactId, or version:

1<dependency>
2    <groupId>com.example</groupId>
3    <artifactId>missing-library</artifactId>
4    <version>1.0.0</version>
5</dependency>

If no configured repository contains that exact artifact, Maven cannot read the descriptor. Before chasing network issues, confirm that the dependency coordinates are real and published where you expect.

Verify the Repositories Maven Is Allowed to Use

Repository configuration errors are the next common cause. Typical examples include:

• the repository URL is wrong
• the repository is private and requires credentials
• the required profile is not active
• a proxy is required but not configured

A project might look fine in IntelliJ while Maven is still pointing at the wrong settings file or missing an enterprise profile. A simple repository block can be enough for public dependencies:

1<repositories>
2    <repository>
3        <id>central</id>
4        <url>https://repo1.maven.org/maven2</url>
5    </repository>
6</repositories>

For private repositories, also check settings.xml for matching server credentials.

Use Terminal Maven for Better Diagnostics

IntelliJ's popup is usually less informative than Maven's own debug output. Run Maven directly:

mvn -U -X dependency:tree

Why this helps:

• '-U forces update checks'
• '-X enables debug logging'
• 'dependency:tree exercises dependency resolution clearly'

If Maven fails in the terminal too, the issue is not the IDE. If terminal Maven works and IntelliJ fails, you likely have an IntelliJ Maven configuration mismatch.

Check IntelliJ's Maven Settings

IntelliJ can use:

• bundled Maven or external Maven
• one user settings.xml file or another
• a custom local repository path

If IntelliJ is not using the same Maven settings as your shell, private repositories and credentials can work in one place and fail in the other.

In IntelliJ, verify:

• Maven home
• user settings file
• local repository path
• active profiles

That comparison often explains why a build succeeds from the terminal but fails inside the IDE.

Clear Corrupted Cache Entries Carefully

Sometimes the remote dependency is valid, but your local cache contains a broken partial download. In that case, delete only the affected artifact path first:

rm -rf ~/.m2/repository/com/example/missing-library

Then reload the project or rerun Maven. Deleting the entire ~/.m2/repository is a blunt tool and often unnecessary.

Snapshot and Private Registry Problems

Snapshot artifacts and private registries cause a disproportionate number of descriptor errors. Common examples are:

• expired Artifactory or Nexus credentials
• GitHub Packages tokens no longer valid
• snapshot metadata not refreshed
• mirrors or repository managers temporarily unavailable

If the dependency is not from Maven Central, test access outside IntelliJ first and confirm that the same account, token, or proxy setup is active in both environments.

A Practical Troubleshooting Order

Use this order to avoid wasting time:

1. confirm the dependency coordinates
2. test Maven in the terminal
3. verify repository URLs and credentials
4. compare IntelliJ Maven settings with terminal Maven
5. clear the specific local cache path if needed

That sequence catches most real causes quickly.

Common Pitfalls

• Treating the issue as an IntelliJ editor bug when Maven resolution is actually failing.
• Deleting the entire Maven cache before checking whether the dependency coordinates are simply wrong.
• Forgetting that IntelliJ may use a different settings.xml than the terminal.
• Ignoring private repository authentication when the artifact is not on Maven Central.
• Chasing POM syntax in the project when the actual problem is network, proxy, or mirror configuration.

Summary

• 'Failed to read artifact descriptor usually means Maven could not resolve a dependency pom.xml.'
• Check the dependency coordinates first because typos are common.
• Use terminal Maven with -U -X for clearer diagnostics than the IDE popup.
• Compare IntelliJ's Maven settings with the working shell environment.
• Remove only the broken local cache path before resorting to deleting all of ~/.m2/repository.