skip to content

What does <relativePath> do in a <parent> declaration, and how does Maven resolve the parent POM?

level: middleimportance: should knowfreq 50%

answer

  1. default ../pom.xml
  2. disk first, then repo
  3. empty <relativePath/> = repo only
  4. coords must match
  5. Non-resolvable parent error

basics

~10 s

<relativePath> tells Maven where on disk to find the parent POM. By default it is ../pom.xml. If the parent isn't there, Maven downloads it from a repository instead.

solid answer

~30 s

When resolving a `<parent>`, Maven first looks at `<relativePath>` (default `../pom.xml`) on the local filesystem. If a POM is found there AND its coordinates match the declared parent, Maven uses it directly — handy in multi-module builds where the parent isn't installed yet. If the file is absent or coordinates don't match, Maven falls back to the local repository and then remote repositories, downloading the parent artifact. Setting `<relativePath/>` (empty) explicitly disables the filesystem lookup, forcing repository resolution — common for an external published parent like spring-boot-starter-parent. A wrong relativePath is a frequent cause of 'Non-resolvable parent POM' errors.

code

xml · 6 lines
xml
<parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>3.3.0</version>
  <relativePath/>
</parent>

go deeper

for a junior

Know the default is ../pom.xml and Maven can also download the parent.

for a middle

Explain the disk-then-repository resolution order and the empty <relativePath/> idiom.

for a senior

Diagnose non-resolvable-parent errors and decide when to pin relativePath vs disable it.

for a principal

Set conventions so internal parents resolve from disk in CI and external parents resolve from a controlled repository/mirror.

## The problem relativePath solves In a multi-module project, a child references a parent that may not yet be installed in your local repository (`~/.m2/repository`). To build the whole tree from source, Maven needs to find the parent **on disk**. `<relativePath>` is the filesystem hint for that. ## Resolution order 1. **relativePath on disk** — default is `../pom.xml` (the directory above the child). If a POM exists there and its `groupId:artifactId:version` matches the declared parent, Maven uses it. 2. **Local repository** — `~/.m2/repository`. 3. **Remote repositories** — download the parent artifact. ## Three common forms ```xml <!-- 1. Default: look at ../pom.xml --> <parent> <groupId>com.acme</groupId> <artifactId>acme-parent</artifactId> <version>1.0.0</version> </parent> <!-- 2. Custom location on disk --> <parent> <groupId>com.acme</groupId> <artifactId>acme-parent</artifactId> <version>1.0.0</version> <relativePath>../../build/parent/pom.xml</relativePath> </parent> <!-- 3. Empty: skip disk, always resolve from repository --> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>3.3.0</version> <relativePath/> </parent> ``` ## Why use empty relativePath For a published external parent (e.g. spring-boot-starter-parent) there is no `../pom.xml`. Without `<relativePath/>`, Maven wastes time probing the filesystem and may even pick up an unrelated POM. The empty tag tells Maven to go straight to the repository. ## Common failures - **'Non-resolvable parent POM'**: relativePath points somewhere wrong and the parent isn't in any repo yet. - **Wrong parent picked up**: a stray `../pom.xml` with matching-ish coordinates. Always keep coordinates exact.

  • Why set <relativePath/> empty for spring-boot-starter-parent?
    There is no parent on disk; the empty tag skips the filesystem probe and resolves it straight from the repository, avoiding wrong-POM pickups and warnings.
  • What happens if relativePath points to a POM with different coordinates?
    Maven ignores that on-disk file (coordinate mismatch) and falls back to repository resolution; if not found there, the build fails with a non-resolvable parent error.

saying these in an interview costs you the question

  • Thinking relativePath is required (default is ../pom.xml)
  • Believing an empty <relativePath/> means the current directory
  • Assuming Maven always downloads the parent and never reads it from disk

context

resolving links…