Print usage when no goals and no POM are specified

[gnodet]

Problem

When a user types mvn without any arguments and there is no pom.xml in the current directory, Maven currently fails with:

[ERROR] No goals have been specified for this build. You must specify a valid lifecycle phase or a goal...
[ERROR] BUILD FAILURE

This is surprising and unhelpful — especially for new users. Tools like java and javac print usage in this situation.

The discussion on the dev list ("Print usage when no arguments are given" Sep 2026) confirmed broad agreement that the current behavior should be improved, with the key constraint that default goals must still work.

Additionally, when the -f/--file option points to a non-existent file, Maven previously printed the same error message twice in different formats:

POM file X does not exist
[ERROR] Error executing Maven.
[ERROR] Error determining top directory
[ERROR] Caused by: POM file X ... does not exist

Solution

1. Print usage when no goals and no POM are present

Override postCommands() in MavenInvoker to detect the following narrow condition:

1. No goals or lifecycle phases were given on the command line.
2. No POM file is present in the current directory (or via -f).

When both are true, print the same help output as mvn -h and exit with code 0.

If a POM is found, Maven proceeds as before: the default goal (if any) is executed, or NoGoalSpecifiedException is reported as today. Existing behavior for all normal project builds is unchanged.

2. Clean up the -f missing-file error message

When getTopDirectory() throws an IllegalArgumentException because the -f/--file argument points to a non-existent path, the exception message is already self-explanatory ("POM file X does not exist"). It is now logged directly instead of being wrapped in the opaque "Error determining top directory" prefix and then repeated as a cause chain. The output is now:

[ERROR] Error executing Maven.
[ERROR] POM file X specified with the -f/--file command line argument does not exist

Why this approach

• No shell script changes needed — shell-script patching would break default goals and require identical changes to mvn.cmd, mvnDebug, etc.
• No full model resolution — we reuse determinePom() which is a cheap file-existence check via ModelProcessor.locateExistingPom(). No parent POM downloads, no DI warmup.
• Right hook point — postCommands() fires after lookup() (DI is ready, context.lookup is available), so determinePom() can be called safely.
• Consistent exit code — exits 0, matching the mvn -h convention.

[gnodet-bot]

Solid approach — three cleanly separated concerns, each independently correct.

1. Print usage on mvn with no goals and no POM (MavenInvoker.postCommands): The guard goals().orElse(List.of()).isEmpty() && determinePom(...) == null is precise — exits 0 with help only when no POM is found, preserving default-goal behavior when a POM exists. Uses the exact same displayHelp + ExitException(0) pattern as helpOrVersionAndMayExit, and fires after lookup() so DI is ready for determinePom().

2. Clean -f error messages (BaseParser): Catching IllegalArgumentException before the generic catch (Exception) lets the already-descriptive message from getTopDirectory() ("POM file X ... does not exist") print directly instead of being wrapped in "Error determining top directory". Same pattern applied symmetrically to getRootDirectory.

3. Shell exit code propagation (mvn): Previously find_file_argument_basedir's exit 1 only left the subshell — now captured via rc=$?; [ $rc -ne 0 ] && exit $rc and re-checked after find_maven_basedir. The echo → printf '[ERROR] ...' switch adds consistency with Maven's Java-side error formatting and better POSIX portability.

No issues found.

This review was generated by an AI agent, Hermès on behalf of @gnodet.

[raupach-e2n]

I would like to suggest a better phrasing. Instead of

POM file X does not exist
[ERROR] Error executing Maven.
[ERROR] Error determining top directory
[ERROR] Caused by: POM file X ... does not exist

Maybe this is sufficient:

[ERROR] Caused by: pom.xml does not exist

[ascheman]

Looks good, and it lines up with the dev@ consensus on the "Print usage when no arguments are given" thread — POM present → the default goal (if any) still runs, otherwise print usage. Keying the Java check on POM presence rather than trying to detect a default goal also neatly side-steps the "detecting a default goal needs the built model, very early in startup" concern raised there. 👍

One cross-platform gap: the [ERROR] reformatting of the -f/--file messages landed in the Unix mvn script but not in the Windows launcher mvn.cmd, which carries the same two messages (:process_file_arg):

echo POM file "%FILE_ARG%" specified the -f/--file command-line argument does not exist >&2
echo Directory "%POM_DIR%" extracted from the -f/--file command-line argument "%FILE_ARG%" does not exist >&2

So Windows users still get the un-prefixed form. Those should become:

echo [ERROR] POM file "%FILE_ARG%" specified with the -f/--file command-line argument does not exist >&2
echo [ERROR] Directory "%POM_DIR%" extracted from the -f/--file command-line argument "%FILE_ARG%" does not exist >&2

(also fixes a stray specified the → specified with the, matching the Unix wording). I'd have made these one-click suggestions, but mvn.cmd isn't part of this PR's diff, so GitHub won't let me anchor a suggestion there — if you add the file they can be applied directly.

The harder half of your Unix change needs no Windows counterpart, though: the subshell-exit propagation (so a bad -f aborts instead of continuing and printing the error twice) has nothing to fix in mvn.cmd — it already aborts on a bad -f via goto error, so it never had the double-error behavior. Only the [ERROR] prefix is missing there.

[ascheman]

Heads-up: CI is red on this PR — initial-build fails at the test-mvn-path-conversion exec (project apache-maven), and it's caused by this change.

All the path-conversion assertions pass (ok - POSIX/CYGWIN/MINGW/MSYS …); the script then aborts (it runs under set -e) at the first -f scenario:

output=`run_mvn_with_args CYGWIN_NT-10.0 "$stub_dir" -f /cygdrive/c/temp/pom.xml validate`

Root cause: this PR makes a non-existent -f/--file a fatal early exit in the launcher — find_file_argument_basedir's exit 1 is now propagated up (the correct fix for the double-error). Previously that "POM file … does not exist" message was printed but non-fatal, so the launcher continued. test-mvn-path-conversion.sh passes simulated, non-existent -f paths — it only checks path conversion, with java stubbed, so the file never had to exist — and under set -e the now-fatal exit aborts the test before it can assert the conversion.

The behavior change is right; the test just needs to catch up — e.g. touch a real file at each -f path the test passes (or point them at an existing stub) so the existence check passes and the conversion assertions still run. (-s scenarios are unaffected — settings files aren't existence-checked in the launcher.)