Introduction

A "non-resolvable parent POM" error in a Spring Boot project means Maven could not download the parent POM needed to build the project model. When the message specifically mentions repo.spring.io and Unknown host, the problem is usually not Spring Boot itself but network resolution, proxy configuration, or an unnecessary repository declaration for a version that should have come from Maven Central.

Why the Parent POM Matters

A typical Spring Boot project uses a parent declaration like this:

1<parent>
2  <groupId>org.springframework.boot</groupId>
3  <artifactId>spring-boot-starter-parent</artifactId>
4  <version>3.2.0</version>
5  <relativePath/>
6</parent>

Maven must resolve that parent before it can fully process the rest of the project. If the parent cannot be downloaded, the build fails early because the project model is incomplete.

Start by Checking Whether You Even Need repo.spring.io

For normal Spring Boot release versions, Maven Central is usually enough. You do not need repo.spring.io for general-availability releases.

That means if your project contains something like this:

1<repositories>
2  <repository>
3    <id>spring-milestones</id>
4    <url>https://repo.spring.io/milestone</url>
5  </repository>
6</repositories>

and you are using a normal release version, you may be adding an extra failure point unnecessarily.

Spring milestone or snapshot repositories are typically needed only for milestone or snapshot versions, not for standard releases.

Verify Network and DNS First

If the error literally says Unknown host, test name resolution outside Maven.

ping repo.spring.io
curl -I https://repo.spring.io/milestone/

If these fail, Maven is only reporting a lower-level connectivity or DNS issue. In that case, fix the network path first instead of editing the POM blindly.

Check Proxy Configuration

Corporate networks are a common cause of this error. Maven needs proxy settings in ~/.m2/settings.xml if outbound access goes through a proxy.

1<settings>
2  <proxies>
3    <proxy>
4      <id>corp-proxy</id>
5      <active>true</active>
6      <protocol>https</protocol>
7      <host>proxy.example.com</host>
8      <port>8080</port>
9    </proxy>
10  </proxies>
11</settings>

If your browser works but Maven does not, proxy configuration is a strong suspect.

You can inspect the effective settings with:

mvn help:effective-settings

Make Sure the Parent Declaration Is Correct

A malformed parent block can produce similar symptoms.

The relativePath line is especially important in many Spring Boot examples:

<relativePath/>

That tells Maven not to search for a local relative parent POM and instead resolve it from repositories.

If that line is missing, Maven may look in places you did not intend before it falls back to remote repositories.

Clear a Broken Local Cache

Sometimes the network issue happened once and Maven cached a bad or partial result. Clearing the local cached parent and forcing an update can help.

rm -rf ~/.m2/repository/org/springframework/boot/spring-boot-starter-parent
mvn clean install -U

The -U flag tells Maven to recheck remote repositories instead of trusting stale local metadata.

A Practical Troubleshooting Sequence

When this error appears, a clean sequence is:

1. confirm the Spring Boot version is real
2. remove unnecessary milestone or snapshot repositories if using a normal release
3. test DNS and connectivity to the repository host
4. inspect Maven proxy settings
5. clear the local parent cache and rerun with -U

This order is faster than changing several things at once and losing track of the real cause.

Read the Error Message Carefully

There is a difference between:

• 'Unknown host, which points to DNS or network access'
• 'Could not find artifact, which often points to version or repository mismatch'
• SSL handshake failures, which suggest certificate or interception issues

Those messages may look similar in a long Maven stack trace, but they suggest different fixes.

Common Pitfalls

The biggest mistake is keeping repo.spring.io in the project when a normal Spring Boot release could have come from Maven Central. That can turn a simple build into a network dependency you never needed.

Another issue is assuming every parent-POM failure is a version typo. If the message says Unknown host, check DNS and proxy configuration first.

Developers also sometimes forget to clear a corrupted local Maven cache, which causes repeated failures even after the external network problem is gone.

Finally, do not debug only the pom.xml. Repository access problems often live in Maven settings, network policy, or developer-machine configuration.

Summary

• Spring Boot parent-POM resolution often relies only on Maven Central for release versions.
• An Unknown host error usually points to DNS, proxy, or network access problems.
• Remove unnecessary Spring milestone or snapshot repository declarations for standard releases.
• Use mvn help:effective-settings and mvn clean install -U during diagnosis.
• Clear the cached parent POM if Maven may have stored a broken local copy.