apache/maven · error · IllegalArgumentException

Invalid threads core multiplier value: '{}'. Value must be p

Error message

Invalid threads core multiplier value: '{}'. Value must be positive.

What it means

The -T / --threads option accepts either a plain integer (thread count) or a number ending in 'C' (a float multiplier of available processors, e.g. -T1.5C). MavenCli.calculateDegreeOfConcurrency() parses the multiplier with Float.parseFloat and requires it to be strictly greater than 0.0f; values like 0C, 0.0C, or -2C throw IllegalArgumentException before the build starts.

Source

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

            final CommandLine commandLine, final String option, final Consumer<Boolean> setting) {
        if (commandLine.hasOption(option)) {
            setting.accept(true);
        }
    }

    private void enableOnPresentOption(
            final CommandLine commandLine, final char option, final Consumer<Boolean> setting) {
        enableOnPresentOption(commandLine, String.valueOf(option), setting);
    }

    int calculateDegreeOfConcurrency(String threadConfiguration) {
        try {
            if (threadConfiguration.endsWith("C")) {
                String str = threadConfiguration.substring(0, threadConfiguration.length() - 1);
                float coreMultiplier = Float.parseFloat(str);

                if (coreMultiplier <= 0.0f) {
                    throw new IllegalArgumentException("Invalid threads core multiplier value: '" + threadConfiguration
                            + "'. Value must be positive.");
                }

                int procs = Runtime.getRuntime().availableProcessors();
                int threads = (int) (coreMultiplier * procs);
                return threads == 0 ? 1 : threads;
            } else {
                int threads = Integer.parseInt(threadConfiguration);
                if (threads <= 0) {
                    throw new IllegalArgumentException(
                            "Invalid threads value: '" + threadConfiguration + "'. Value must be positive.");
                }
                return threads;
            }
        } catch (NumberFormatException e) {
            throw new IllegalArgumentException("Invalid threads value: '" + threadConfiguration
                    + "'. Supported are int and float values ending with C.");
        }

View on GitHub (pinned to e4093d4e12)

Solutions

Use a strictly positive multiplier: -T1C (one thread per core, the safe default), -T2C, or -T0.5C.
Fix the variable feeding the option: default THREADS=1 (not 0) in CI, e.g. mvn -T${THREADS:-1}C.
If you want a fixed number of worker threads, use the integer form -T4 instead of a multiplier.
Omit -T entirely for fully serial builds rather than passing -T0C.

Example fix

# before
mvn -T${THREADS}C package   # THREADS=0 -> IllegalArgumentException

# after
mvn -T${THREADS:-1}C package

Defensive patterns

Strategy: validation

Validate before calling

// Validate a -T value before invoking mvn
static int degreeOfConcurrency(String v) {
    if (v.endsWith("C") || v.endsWith("c")) {
        float m = Float.parseFloat(v.substring(0, v.length() - 1));
        if (m <= 0f) throw new IllegalArgumentException("multiplier must be > 0: " + v);
        int t = (int) (m * Runtime.getRuntime().availableProcessors());
        return Math.max(t, 1);
    }
    int n = Integer.parseInt(v);
    if (n <= 0) throw new IllegalArgumentException("threads must be > 0: " + v);
    return n;
}
// launcher: degreeOfConcurrency(threadCfg); // throws before a half-started build

Try / catch

try {
    mavenCli.doMain(args, ...);
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Invalid threads core multiplier value")) {
        // fall back to -T1C and re-invoke once
    }
    throw e;
}

Prevention

Default CI thread variables to 1, never 0: -T${THREADS:-1}C.
Validate the -T value in your launcher with the same rule (int > 0, or float+C > 0) before spawning mvn.
Treat computed thread counts of 0 from nproc/cgroup quotas as bugs in the environment, and clamp to 1.

When it happens

Trigger: mvn -T0C, mvn -T-0.5C, mvn -T0.0C. Dynamically built command lines such as -T${THREADS}C where THREADS is unset-but-defaulted to 0, empty, or a negative number from a CI variable.

Common situations: CI templates parameterizing thread count via environment variables that default to 0 or empty on some runners. Scripts computing a multiplier that can round down to zero on small/oversubscribed agents. Copy-pasting -T0C from notes where 0 was meant as 'auto' (which is not a thing here; the default -T1C-equivalent applies when the flag is omitted).

Related errors

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