apache/maven · error · IllegalArgumentException

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

Error message

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

What it means

When the -T / --threads value does not end in 'C', MavenCli.calculateDegreeOfConcurrency() parses it as an integer thread count and requires it to be greater than 0. Values like 0, -2, or 00 throw IllegalArgumentException ('Invalid threads value ... Value must be positive.') during CLI configuration, before any project builds.

Source

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

    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.");
        }
    }

    // ----------------------------------------------------------------------
    // Properties handling
    // ----------------------------------------------------------------------

    void populateProperties(
            CommandLine commandLine, Properties paths, Properties systemProperties, Properties userProperties)
            throws Exception {

View on GitHub (pinned to e4093d4e12)

Solutions

1. Pass a positive integer: -T4, or fall back to 1: -T${JOBS:-1}.
2. Guard the derived value in your script: JOBS=$(nproc); [ "$JOBS" -lt 1 ] && JOBS=1 before building the -T argument.
3. Prefer the multiplier form -T1C to scale with actual available processors instead of computing counts yourself.
4. Omit -T for serial builds.

Example fix

# before
JOBS=$(nproc)   # returns 0 in a cgroup-limited container
mvn -T${JOBS} package

# after
JOBS=$(nproc); [ "$JOBS" -lt 1 ] && JOBS=1
mvn -T${JOBS} package

String v = argAfter(args, "-T", "--threads");
if (v != null && !v.toUpperCase(Locale.ROOT).endsWith("C")) {
    int n = Integer.parseInt(v); // NumberFormatException here = your bug, caught in launcher
    if (n <= 0) throw new IllegalArgumentException("-T must be a positive int: " + v);
}

try {
    mavenCli.doMain(args, ...);
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Invalid threads value")
            && e.getMessage().contains("must be positive")) {
        // replace with -T1 (or drop -T) and re-invoke
    }
    throw e;
}

When it happens

Trigger: mvn -T0, mvn -T-2, mvn -T0x4. Templated command lines like -T${JOBS} where JOBS is 0 (e.g. nproc returning 0 in restricted containers, or a failed arithmetic default), producing the option value 0.

Common situations: CI pipelines deriving -T from container CPU counts (nproc/cpu quota) that yield 0 on throttled runners. Scripts defaulting a jobs variable to 0 to mean 'auto'. Renaming a variable so the interpolation becomes empty or 0.

Related errors

• Invalid threads core multiplier value: '{}'. Value must be p
• Invalid threads value: '{}'. Supported are int and float val
• Invalid color configuration value '{}'. Supported are 'auto'
• {} is not a valid log severity threshold. Valid severities a
• Unbounded range: {}

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