apache/maven · error · IllegalArgumentException

The POM found does not belong to the given directory: ${pom}

Error message

The POM found does not belong to the given directory: ${pom}

What it means

DefaultModelProcessor.locateExistingPom(Path projectDirectory) asks every registered ModelParser (the standard pom.xml parser plus any polyglot extensions) to find a build file for the directory. The result must be the directory itself or a direct child of it; if a parser returns a path outside the directory, IllegalArgumentException is thrown to stop a parser from escaping the project directory.

Source

Thrown at impl/maven-impl/src/main/java/org/apache/maven/impl/model/DefaultModelProcessor.java:92

    @Inject
    public DefaultModelProcessor(ModelXmlFactory modelXmlFactory, @Nullable Map<String, ModelParser> modelParsers) {
        this.modelXmlFactory = modelXmlFactory;
        this.modelParsers = modelParsers;
    }

    @Override
    public Path locateExistingPom(Path projectDirectory) {
        // Note that the ModelProcessor#locatePom never returns null
        // while the ModelParser#locatePom needs to return an existing path!
        Path pom = modelParsers.values().stream()
                .map(m -> m.locate(projectDirectory)
                        .map(org.apache.maven.api.services.Source::getPath)
                        .orElse(null))
                .filter(Objects::nonNull)
                .findFirst()
                .orElseGet(() -> doLocateExistingPom(projectDirectory));
        if (pom != null && !pom.equals(projectDirectory) && !pom.getParent().equals(projectDirectory)) {
            throw new IllegalArgumentException("The POM found does not belong to the given directory: " + pom);
        }
        return pom;
    }

    @Override
    public Model read(XmlReaderRequest request) throws IOException {
        Objects.requireNonNull(request, "source cannot be null");
        Path pomFile = request.getPath();
        if (pomFile != null) {
            Path projectDirectory = pomFile.getParent();
            Map<String, ModelParserException> exceptions = new LinkedHashMap<>();
            for (Map.Entry<String, ModelParser> parser : modelParsers.entrySet()) {
                try {
                    Optional<Model> model = parser.getValue()
                            .locateAndParse(projectDirectory, Map.of(ModelParser.STRICT, request.isStrict()));
                    if (model.isPresent()) {
                        return model.get().withPomFile(pomFile);
                    }

View on GitHub (pinned to e4093d4e12)

Solutions

Inspect .mvn/extensions.xml (and any core extensions in settings) for polyglot parsers and disable or update the offending one
Fix the custom ModelParser.locate so it only ever returns a file inside the given directory
Call locateExistingPom with the directory that actually contains the build file

Example fix

// before: parser escapes the directory
public Optional<Source> locate(Path dir) {
    return Optional.of(buildSource(dir.getParent().resolve("build.gradle")));
}

// after: only look inside the directory
public Optional<Source> locate(Path dir) {
    Path f = dir.resolve("build.gradle");
    return Files.isRegularFile(f) ? Optional.of(buildSource(f)) : Optional.empty();
}

Defensive patterns

Strategy: validation

Validate before calling

Path pom = modelProcessor.locateExistingPom(projectDirectory);
// post-condition, mirrors the guard in locateExistingPom
if (pom != null && !pom.equals(projectDirectory) && !pom.getParent().equals(projectDirectory)) {
    throw new IllegalArgumentException("Located pom escapes the project directory: " + pom);
}

Try / catch

try {
    Path pom = modelProcessor.locateExistingPom(dir);
} catch (IllegalArgumentException e) {
    // an extension parser claimed a build file outside dir; disable polyglot extensions and retry
}

Prevention

Keep polyglot/extension ModelParsers strictly scoped: locate() must only return files inside the given directory
Pin extension versions in .mvn/extensions.xml so a parser behavior change cannot surprise the build
Add a unit test for custom parsers asserting the returned path's parent equals the input directory

When it happens

Trigger: A polyglot or custom ModelParser whose locate(projectDirectory) resolves to a build file in a parent or sibling directory (e.g. a Gradle/BND file up the tree), so pom.getParent() differs from projectDirectory.

Common situations: polyglot-maven extensions declared in .mvn/extensions.xml; in-house ModelParser implementations that search upwards instead of only inside the given directory; symlinked checkouts where resolution leaves the module tree.

Related errors

AI-assisted analysis of apache/maven@e4093d4e12 (2026-08-21). Data as JSON: /api/errors/a5f65b12e1e6f2b3. Report an issue: GitHub.