apache/maven · error · IllegalArgumentException

Failed to parse command line options: {}

Error message

Failed to parse command line options: {}

What it means

The Maven upgrade helper (mvnup) parses its own command line with CommonsCliUpgradeOptions; a ParseException is rethrown as IllegalArgumentException 'Failed to parse command line options' with the reason. Only the upgrade tool's options are in scope, not general mvn build options.

Source

Thrown at impl/maven-cli/src/main/java/org/apache/maven/cling/invoker/mvnup/UpgradeParser.java:31

 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
package org.apache.maven.cling.invoker.mvnup;

import org.apache.commons.cli.ParseException;
import org.apache.maven.api.cli.Options;
import org.apache.maven.cling.invoker.BaseParser;

public class UpgradeParser extends BaseParser {
    @Override
    protected Options parseCliOptions(LocalContext context) {
        try {
            return CommonsCliUpgradeOptions.parse(context.parserRequest.args().toArray(new String[0]));
        } catch (ParseException e) {
            throw new IllegalArgumentException("Failed to parse command line options: " + e.getMessage(), e);
        }
    }
}

View on GitHub (pinned to e4093d4e12)

Solutions

1. Run the tool's help output and use only the listed options.
2. Correct or drop the flag named in the ParseException text.
3. Ensure each value-taking option has its value on the command line.

Example fix

# before: unknown option
mvn up --dry-run-apply

# after: use the tool's actual option spelling (check `mvn up --help`)
mvn up --help

try {
    new UpgradeParser().parseCliOptions(context);
} catch (IllegalArgumentException e) {
    showUpgradeUsageAndExit(e.getMessage());
}

When it happens

Trigger: Passing an option the upgrade tool does not define, a misspelled long option, or a value-taking option without its value; flags valid only in a different Maven version's tool.

Common situations: Trying the new upgrade tool with habitual mvn flags; CI wrappers appending global options to all tool invocations; docs from a different tool version.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Failed to parse CLI arguments: ${message}
• Failed to parse arguments from file (${atFile}): ${message}
• Failed to parse command line options: ${message}
• Failed to parse command line options: {}
• Unbounded range: {}

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