apache/maven · error · IllegalArgumentException

Invalid color configuration value '{}'. Supported are 'auto'

Error message

Invalid color configuration value '{}'. Supported are 'auto', 'always', 'never'.

What it means

MavenCli resolves the log color setting from three places in order of precedence: the 'style.color' user property, the 'maven.style.color' user property, and the --color CLI option. The resolved string must be one of 'always', 'yes', 'force', 'never', 'no', 'none', 'auto', 'tty', or 'if-tty' (case-sensitive). Any other value throws IllegalArgumentException during CLI startup (MavenCli.logging()), before any project is read or built. Although the message names only three values, the aliases above are also accepted.

Source

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

     * configure logging
     */
    void logging(CliRequest cliRequest) throws ExitException {
        // LOG LEVEL
        CommandLine commandLine = cliRequest.commandLine;
        cliRequest.verbose = commandLine.hasOption(CLIManager.VERBOSE) || commandLine.hasOption(CLIManager.DEBUG);
        cliRequest.quiet = !cliRequest.verbose && commandLine.hasOption(CLIManager.QUIET);
        cliRequest.showErrors = cliRequest.verbose || commandLine.hasOption(CLIManager.ERRORS);

        // LOG COLOR
        String styleColor = cliRequest.getUserProperties().getProperty("style.color", "auto");
        styleColor = cliRequest.getUserProperties().getProperty(Constants.MAVEN_STYLE_COLOR_PROPERTY, styleColor);
        styleColor = commandLine.getOptionValue(CLIManager.COLOR, styleColor);
        if ("always".equals(styleColor) || "yes".equals(styleColor) || "force".equals(styleColor)) {
            MessageUtils.setColorEnabled(true);
        } else if ("never".equals(styleColor) || "no".equals(styleColor) || "none".equals(styleColor)) {
            MessageUtils.setColorEnabled(false);
        } else if (!"auto".equals(styleColor) && !"tty".equals(styleColor) && !"if-tty".equals(styleColor)) {
            throw new IllegalArgumentException(
                    "Invalid color configuration value '" + styleColor + "'. Supported are 'auto', 'always', 'never'.");
        } else {
            boolean isBatchMode = !commandLine.hasOption(CLIManager.FORCE_INTERACTIVE)
                    && (commandLine.hasOption(CLIManager.BATCH_MODE)
                            || commandLine.hasOption(CLIManager.NON_INTERACTIVE));
            if (isBatchMode || commandLine.hasOption(CLIManager.LOG_FILE)) {
                MessageUtils.setColorEnabled(false);
            }
        }

        slf4jLoggerFactory = LoggerFactory.getILoggerFactory();
        Slf4jConfiguration slf4jConfiguration = Slf4jConfigurationFactory.getConfiguration(slf4jLoggerFactory);

        if (cliRequest.verbose) {
            cliRequest.request.setLoggingLevel(MavenExecutionRequest.LOGGING_LEVEL_DEBUG);
            slf4jConfiguration.setRootLoggerLevel(Slf4jConfiguration.Level.DEBUG);
        } else if (cliRequest.quiet) {
            cliRequest.request.setLoggingLevel(MavenExecutionRequest.LOGGING_LEVEL_ERROR);

View on GitHub (pinned to e4093d4e12)

Solutions

Change the value to one of the accepted strings: 'auto' (default), 'always', or 'never' (aliases: yes/force, no/none, tty/if-tty).
Check MAVEN_OPTS, ~/.mavenrc, .mvn/maven.config and CI environment for a -Dstyle.color or -Dmaven.style.color property and fix or remove it.
Remove quotes/whitespace around the value, e.g. use --color=always not --color='always ' and verify the value is lowercase.
If you only wanted to force colors in CI, prefer the canonical form mvn -B --color=never or a TTY wrapper instead of boolean-style values.

Example fix

# before
mvn --color=true
MAVEN_OPTS='-Dstyle.color=on'

# after
mvn --color=always
MAVEN_OPTS='-Dstyle.color=always'

Defensive patterns

Strategy: validation

Validate before calling

// Java, before invoking the CLI
Set<String> ok = Set.of("auto", "tty", "if-tty", "always", "yes", "force", "never", "no", "none");
String color = firstNonNull(userProps.getProperty("maven.style.color"),
                            userProps.getProperty("style.color"),
                            cliArgValue("--color")); // whatever your launcher passes
if (color != null && !ok.contains(color)) {
    throw new IllegalArgumentException("Rejecting invalid color value before mvn launch: " + color);
}

Try / catch

// When embedding: catch around MavenCli.doMain
try {
    cli.doMain(args, workingDir, ...);
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Invalid color configuration value")) {
        // surface a friendly message; fix config and retry once
    }
    throw e;
}

Prevention

Keep a single source of truth for style.color (ideally .mvn/maven.config) instead of scattering -D flags through MAVEN_OPTS and CI variables.
Never use boolean-style color values (true/1/on) with Maven; the vocabulary is auto/always/never plus aliases.
Add a pipeline lint step that greps MAVEN_OPTS and maven.config for style.color values outside the accepted set.

When it happens

Trigger: Running mvn --color=true, --color=on, --color=1, or --color=Always (capitalized). Setting -Dstyle.color or -Dmaven.style.color (e.g. in MAVEN_OPTS, .mvn/maven.config, or CI environment) to a value outside the accepted set. A trailing space or quotes surviving into the property value also triggers it, because comparison is exact String.equals.

Common situations: Porting color settings from other tools (git color.ui=true, CLICOLOR_FORCE=1 style conventions) to Maven. CI pipelines exporting -Dstyle.color with a boolean value. Upgrading from setups where the property was ignored. Setting the property globally in MAVEN_OPTS and forgetting it is validated on every mvn invocation.

Related errors

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