pinpoint-apm/pinpoint · error · IllegalArgumentException

num cannot be negative

Error message

num cannot be negative

What it means

MathUtils.roundToNearestMultipleOf rounds a non-negative long to the nearest multiple of a positive value. Negative num values are rejected with IllegalArgumentException because rounding semantics were only defined for non-negative inputs. Callers must guarantee num >= 0.

Solutions

1. Clamp the value before calling: Math.max(0, num)
2. Fix the upstream calculation producing the negative number
3. If negatives are legitimate input, add a documented guard or reject earlier

Example fix

// before
long rounded = MathUtils.roundToNearestMultipleOf(num, 1000); // num = -5
// after
long rounded = MathUtils.roundToNearestMultipleOf(Math.max(0, num), 1000);

if (num < 0) throw new IllegalArgumentException("num must be >= 0: " + num);
long rounded = MathUtils.roundToNearestMultipleOf(num, multipleOf);

try {
    rounded = MathUtils.roundToNearestMultipleOf(num, multipleOf);
} catch (IllegalArgumentException e) {
    logger.warn("roundToNearestMultipleOf misused: {}", e.getMessage());
    rounded = multipleOf; // safe fallback per method contract
}

When it happens

Trigger: Calling roundToNearestMultipleOf(num, multipleOf) with a negative num, e.g. a negative timestamp delta, offset, or a subtraction that went below zero.

Common situations: Computing elapsed/size values that unexpectedly go negative due to clock skew or underflow; passing unvalidated user-supplied numbers.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• cannot round to nearest multiple of values less than 1
• denominator must be different from 0
• negative maxLength:+maxLength
• negative maxWidth:+maxWidth
• Illegal Capacity: +initialCapacity

AI-assisted analysis of pinpoint-apm/pinpoint@744c3d3075 (2026-09-07). Data as JSON: /api/errors/65e229eb0f45a0f4. Report an issue: GitHub.

Appendix: source

Thrown at commons/src/main/java/com/navercorp/pinpoint/common/util/MathUtils.java:32

 * limitations under the License.
 */

package com.navercorp.pinpoint.common.util;

/**
 * @author emeroad
 */
public final class MathUtils {
    private MathUtils() {
    }

    public static int fastAbs(final int value) {
        return value & Integer.MAX_VALUE;
    }

    public static long roundToNearestMultipleOf(final long num, final long multipleOf) {
        if (num < 0) {
            throw new IllegalArgumentException("num cannot be negative");
        }
        if (multipleOf < 1) {
            throw new IllegalArgumentException("cannot round to nearest multiple of values less than 1");
        }
        if (num < multipleOf) {
            return multipleOf;
        }
        if ((num % multipleOf) >= (multipleOf / 2.0)) {
            return (num + multipleOf) - (num % multipleOf);
        } else {
            return num - (num % multipleOf);
        }
    }


    // copy Apache commons-math 3.6.1 FastMath.floorMod(long, long)
    /** Finds q such that a = q b + r with 0 <= r < b if b > 0 and b < r <= 0 if b < 0.
     * <p>

View on GitHub (pinned to 744c3d3075)