apache/seatunnel · error · IllegalArgumentException

Utilization values must be between 0 and 1

Error message

Utilization values must be between 0 and 1

What it means

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.

Solutions

  1. Normalize metrics to [0,1] before calling: divide percentages by 100 and clamp with Math.max(0, Math.min(1, value))
  2. Fix the metric source to return ratios rather than percentages or sentinel negative values
  3. Guard against failed probes by skipping samples with negative values instead of recording them
  4. Add unit tests covering 0 and 1 boundary values

Example fix

// before
loadCalculator.addUtilizationData(cpuPercent, memPercent); // e.g. 85.0
// after
loadCalculator.addUtilizationData(cpuPercent / 100.0, memPercent / 100.0); // 0.85
Defensive patterns

Strategy: validation

Validate before calling

public static void checkUtilization(double cpu, double mem) {
  if (cpu < 0 || cpu > 1 || mem < 0 || mem > 1) {
    throw new IllegalArgumentException("Utilization must be in [0,1], got cpu=" + cpu + " mem=" + mem);
  }
}

Type guard

function isUtilization(v) { return typeof v === 'number' && v >= 0 && v <= 1; }

Try / catch

try {
  loadCalculator.addUtilizationData(cpu, mem);
} catch (IllegalArgumentException e) {
  log.warn("Dropping invalid utilization sample", e); // skip sample, keep balancer running
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/ef5e9ef50ae63f60. Report an issue: GitHub.

Appendix: source

Thrown at seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/utils/SystemLoadCalculate.java:68

            this.cpuUtilization = cpuUtilization;
            this.memoryUtilization = memoryUtilization;
        }
    }

    private final LinkedList<UtilizationData> utilizationHistory;

    public SystemLoadCalculate() {
        this.utilizationHistory = new LinkedList<>();
    }

    /** Add new resource utilization data */
    public void addUtilizationData(double cpuUtilization, double memoryUtilization) {
        // Validate input data
        if (cpuUtilization < 0
                || cpuUtilization > 1
                || memoryUtilization < 0
                || memoryUtilization > 1) {
            throw new IllegalArgumentException("Utilization values must be between 0 and 1");
        }

        if (utilizationHistory.size() >= MAX_TIME_WINDOW) {
            utilizationHistory.removeLast(); // Remove the oldest record
        }
        utilizationHistory.addFirst(new UtilizationData(cpuUtilization, memoryUtilization));
    }

    /** Generate corresponding time weights based on the actual number of records */
    private double[] generateTimeWeights() {
        int size = utilizationHistory.size();
        if (size == 0) return new double[0];

        // Determine the actual number of weights to use
        int weightCount = Math.min(size, TIME_WEIGHT_RATIOS.length);
        double[] weights = new double[size];
        double totalWeight = 0;

View on GitHub (pinned to cf67b549a7)