apache/maven · error · ExitException

POM file {} specified with the -f/--file command line argume

Error message

POM file {} specified with the -f/--file command line argument does not exist

What it means

During the early -f/--file scan in MavenCli, the value following -f/--file is resolved against the top directory; if it is neither an existing directory nor an existing regular file, 'POM file <arg> specified with the -f/--file command line argument does not exist' is printed to stderr and ExitException terminates the CLI with exit code 1 before any parsing or container startup happens.

Source

Thrown at compat/maven-embedder/src/main/java/org/apache/maven/cli/MavenCli.java:376

        Path topDirectory = fileSystem.getPath(cliRequest.workingDirectory);
        boolean isAltFile = false;
        for (String arg : cliRequest.args) {
            if (isAltFile) {
                // this is the argument following -f/--file
                Path path = topDirectory.resolve(stripLeadingAndTrailingQuotes(arg));
                if (Files.isDirectory(path)) {
                    topDirectory = path;
                } else if (Files.isRegularFile(path)) {
                    topDirectory = path.getParent();
                    if (!Files.isDirectory(topDirectory)) {
                        System.err.println("Directory " + topDirectory
                                + " extracted from the -f/--file command-line argument " + arg + " does not exist");
                        throw new ExitException(1);
                    }
                } else {
                    System.err.println(
                            "POM file " + arg + " specified with the -f/--file command line argument does not exist");
                    throw new ExitException(1);
                }
                break;
            } else {
                // Check if this is the -f/--file option
                isAltFile = arg.equals("-f") || arg.equals("--file");
            }
        }
        topDirectory = getCanonicalPath(topDirectory);
        cliRequest.topDirectory = topDirectory;
        // We're very early in the process, and we don't have the container set up yet,
        // so we rely on the JDK services to eventually look up a custom RootLocator.
        // This is used to compute {@code session.rootDirectory} but all {@code project.rootDirectory}
        // properties will be computed through the RootLocator found in the container.
        RootLocator rootLocator =
                ServiceLoader.load(RootLocator.class).iterator().next();
        cliRequest.rootDirectory = rootLocator.findRoot(topDirectory);

        //

View on GitHub (pinned to e4093d4e12)

Solutions

Verify the file exists from the directory you launch mvn from: ls <value-of-f>
Correct the path or cd into the module and run mvn without -f
In scripts, derive the path robustly (absolute path via $(pwd)) rather than assuming the launch directory
Re-check the path after moving/renaming modules in a multi-module repo

Example fix

# before
mvn -f mudules/app/pom.xml package   # typo

# after
mvn -f modules/app/pom.xml package

Defensive patterns

Strategy: validation

Validate before calling

import java.nio.file.*;

// validate a -f/--file value before launching Maven
Path p = Paths.get(fValue);
if (!(Files.isDirectory(p) || Files.isRegularFile(p))) {
    throw new IllegalArgumentException(
        "-f target does not exist relative to " + System.getProperty("user.dir") + ": " + fValue);
}

Try / catch

catch (ExitException e) {
    if (stderrCapture.contains("specified with the -f/--file command line argument does not exist")) {
        // recompute the correct module path (e.g. locate pom.xml upward) and retry once
        Path pom = findPomUpwards(Paths.get("").toAbsolutePath());
        if (pom != null) retryWithArguments(replaceArgument(args, fValue, pom.toString()));
    }
}

Prevention

In scripts, compute -f from a verified absolute base: mvn -f "$(pwd)/modules/app/pom.xml"
After moving or renaming modules, grep build scripts for stale -f paths
On Windows, check for stray literal quotes in path arguments — Maven strips only leading/trailing ones

When it happens

Trigger: mvn -f path/to/pom.xml (or --file) where the path does not exist relative to the current working directory: typo, wrong working directory, module pom deleted or renamed, or a quoted path containing stray characters (the CLI strips leading/trailing quotes before resolving).

Common situations: Running mvn -f subdir/pom.xml from the wrong module root; CI checkouts where the expected module path moved; renamed pom.xml (e.g. to pom.xml.template) still referenced in scripts; Windows path quoting issues where quotes reach the JVM.

Related errors

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