pinpoint-apm/pinpoint · error · IllegalArgumentException

cannot round to nearest multiple of values less than 1

Error message

cannot round to nearest multiple of values less than 1

What it means

MathUtils.roundToNearestMultipleOf requires the multipleOf argument to be at least 1; zero, negative, or fractional-less values would cause division by zero or undefined rounding. The library throws IllegalArgumentException to signal the misuse.

Solutions

1. Ensure the rounding interval is a positive constant (>= 1) before calling
2. Validate config: reject interval <= 0 at startup
3. Guard the call site with a fallback default like 1

Example fix

// before
long rounded = MathUtils.roundToNearestMultipleOf(num, interval); // interval = 0
// after
long step = interval >= 1 ? interval : 1;
long rounded = MathUtils.roundToNearestMultipleOf(num, step);

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

try {
    rounded = MathUtils.roundToNearestMultipleOf(num, multipleOf);
} catch (IllegalArgumentException e) {
    logger.warn("invalid multipleOf: {}", e.getMessage());
    rounded = num;
}

When it happens

Trigger: Calling roundToNearestMultipleOf(num, multipleOf) with multipleOf < 1, typically 0 from an unset config or a negative interval value.

Common situations: A rounding interval configured as 0 because the property was missing; a computed step size of 0 from an empty aggregation.

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

• num cannot be negative
• 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/07df233dc560c3da. Report an issue: GitHub.

Appendix: source

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

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>
     * This methods returns the same value as integer division when
     * a and b are same signs, but returns a different value when
     * they are opposite (i.e. q is negative).

View on GitHub (pinned to 744c3d3075)