{"record":{"id":"ef5e9ef50ae63f60","repo":"apache/seatunnel","slug":"utilization-values-must-be-between-0-and-1","errorCode":null,"errorMessage":"Utilization values must be between 0 and 1","messagePattern":"Utilization values must be between 0 and 1","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/utils/SystemLoadCalculate.java","lineNumber":68,"sourceCode":"            this.cpuUtilization = cpuUtilization;\n            this.memoryUtilization = memoryUtilization;\n        }\n    }\n\n    private final LinkedList<UtilizationData> utilizationHistory;\n\n    public SystemLoadCalculate() {\n        this.utilizationHistory = new LinkedList<>();\n    }\n\n    /** Add new resource utilization data */\n    public void addUtilizationData(double cpuUtilization, double memoryUtilization) {\n        // Validate input data\n        if (cpuUtilization < 0\n                || cpuUtilization > 1\n                || memoryUtilization < 0\n                || memoryUtilization > 1) {\n            throw new IllegalArgumentException(\"Utilization values must be between 0 and 1\");\n        }\n\n        if (utilizationHistory.size() >= MAX_TIME_WINDOW) {\n            utilizationHistory.removeLast(); // Remove the oldest record\n        }\n        utilizationHistory.addFirst(new UtilizationData(cpuUtilization, memoryUtilization));\n    }\n\n    /** Generate corresponding time weights based on the actual number of records */\n    private double[] generateTimeWeights() {\n        int size = utilizationHistory.size();\n        if (size == 0) return new double[0];\n\n        // Determine the actual number of weights to use\n        int weightCount = Math.min(size, TIME_WEIGHT_RATIOS.length);\n        double[] weights = new double[size];\n        double totalWeight = 0;\n","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/utils/SystemLoadCalculate.java#L50-L86","documentation":"SystemLoadCalculate.addUtilizationData validates that CPU and memory utilization are fractions in [0,1] before recording them into its load-balancer history. Values outside this range indicate bad metrics collection (e.g. percentages 0-100 instead of 0-1) and are rejected with this IllegalArgumentException.","triggerScenarios":"Calling addUtilizationData with cpuUtilization or memoryUtilization < 0 or > 1 — most commonly passing 55.0 when the API expects 0.55, negative values from failed metric probes, or NaN-adjacent computations that fall outside the range.","commonSituations":"Custom load balancers feeding percentage-scaled metrics (0-100) instead of ratios, monitoring plugins reporting -1 on collection failure, or unit conversions skipped between metric sources and the balancer.","solutions":["Normalize metrics to [0,1] before calling: divide percentages by 100 and clamp with Math.max(0, Math.min(1, value))","Fix the metric source to return ratios rather than percentages or sentinel negative values","Guard against failed probes by skipping samples with negative values instead of recording them","Add unit tests covering 0 and 1 boundary values"],"exampleFix":"// before\nloadCalculator.addUtilizationData(cpuPercent, memPercent); // e.g. 85.0\n// after\nloadCalculator.addUtilizationData(cpuPercent / 100.0, memPercent / 100.0); // 0.85","handlingStrategy":"validation","validationCode":"public static void checkUtilization(double cpu, double mem) {\n  if (cpu < 0 || cpu > 1 || mem < 0 || mem > 1) {\n    throw new IllegalArgumentException(\"Utilization must be in [0,1], got cpu=\" + cpu + \" mem=\" + mem);\n  }\n}","typeGuard":"function isUtilization(v) { return typeof v === 'number' && v >= 0 && v <= 1; }","tryCatchPattern":"try {\n  loadCalculator.addUtilizationData(cpu, mem);\n} catch (IllegalArgumentException e) {\n  log.warn(\"Dropping invalid utilization sample\", e); // skip sample, keep balancer running\n}","preventionTips":["Divide percentage metrics (0-100) by 100 before recording","Clamp metrics: Math.max(0, Math.min(1, value))","Treat negative sentinel values from metric sources as missing data, not samples","Add boundary tests for 0.0 and 1.0"],"tags":["validation","load-balancer","metrics"],"backgroundTag":"value-out-of-range","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}