{"record":{"id":"65e229eb0f45a0f4","repo":"pinpoint-apm/pinpoint","slug":"num-cannot-be-negative","errorCode":null,"errorMessage":"num cannot be negative","messagePattern":"num cannot be negative","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"commons/src/main/java/com/navercorp/pinpoint/common/util/MathUtils.java","lineNumber":32,"sourceCode":" * limitations under the License.\n */\n\npackage com.navercorp.pinpoint.common.util;\n\n/**\n * @author emeroad\n */\npublic final class MathUtils {\n    private MathUtils() {\n    }\n\n    public static int fastAbs(final int value) {\n        return value & Integer.MAX_VALUE;\n    }\n\n    public static long roundToNearestMultipleOf(final long num, final long multipleOf) {\n        if (num < 0) {\n            throw new IllegalArgumentException(\"num cannot be negative\");\n        }\n        if (multipleOf < 1) {\n            throw new IllegalArgumentException(\"cannot round to nearest multiple of values less than 1\");\n        }\n        if (num < multipleOf) {\n            return multipleOf;\n        }\n        if ((num % multipleOf) >= (multipleOf / 2.0)) {\n            return (num + multipleOf) - (num % multipleOf);\n        } else {\n            return num - (num % multipleOf);\n        }\n    }\n\n\n    // copy Apache commons-math 3.6.1 FastMath.floorMod(long, long)\n    /** Finds q such that a = q b + r with 0 <= r < b if b > 0 and b < r <= 0 if b < 0.\n     * <p>","sourceCodeStart":14,"sourceCodeEnd":50,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/commons/src/main/java/com/navercorp/pinpoint/common/util/MathUtils.java#L14-L50","documentation":"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.","triggerScenarios":"Calling roundToNearestMultipleOf(num, multipleOf) with a negative num, e.g. a negative timestamp delta, offset, or a subtraction that went below zero.","commonSituations":"Computing elapsed/size values that unexpectedly go negative due to clock skew or underflow; passing unvalidated user-supplied numbers.","solutions":["Clamp the value before calling: Math.max(0, num)","Fix the upstream calculation producing the negative number","If negatives are legitimate input, add a documented guard or reject earlier"],"exampleFix":"// before\nlong rounded = MathUtils.roundToNearestMultipleOf(num, 1000); // num = -5\n// after\nlong rounded = MathUtils.roundToNearestMultipleOf(Math.max(0, num), 1000);","handlingStrategy":"validation","validationCode":"if (num < 0) throw new IllegalArgumentException(\"num must be >= 0: \" + num);\nlong rounded = MathUtils.roundToNearestMultipleOf(num, multipleOf);","typeGuard":null,"tryCatchPattern":"try {\n    rounded = MathUtils.roundToNearestMultipleOf(num, multipleOf);\n} catch (IllegalArgumentException e) {\n    logger.warn(\"roundToNearestMultipleOf misused: {}\", e.getMessage());\n    rounded = multipleOf; // safe fallback per method contract\n}","preventionTips":["Clamp computed values with Math.max(0, x) before rounding","Watch for clock-skew-induced negative durations","Add assertions where negative values indicate upstream bugs"],"tags":["math","argument-check","pinpoint-commons"],"backgroundTag":"invalid-argument-value","analyzedSha":"744c3d3075e595656abb1ae331ad2c0e4c9eb996","analyzedAt":"2026-09-07T18:48:45.289Z","contentChangedAt":"2026-09-07T18:48:45.289Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}