pentaho/pentaho-kettle · error · IllegalArgumentException

: Collator strength must be an int between 0 and 3.

Error message

 : Collator strength must be an int between 0 and 3.

What it means

ValueMetaBase.setCollatorStrength validates the java.text.Collator strength argument; Collator.setStrength throws IllegalArgumentException for values outside PRIMARY(0), SECONDARY(1), TERTIARY(2), IDENTICAL(3). The library rethrows with a message beginning ' : Collator strength must be an int between 0 and 3.'

Solutions

  1. Pass only Collator.PRIMARY (0), SECONDARY (1), TERTIARY (2), or IDENTICAL (3)
  2. Validate/clamp the configured strength before calling setCollatorStrength
  3. Catch IllegalArgumentException and fall back to the default strength
  4. Confirm the collator itself is non-null — the check only applies when collator != null

Example fix

// before
valueMeta.setCollatorStrength(5); // throws
// after
int strength = Math.min(3, Math.max(0, configuredStrength));
valueMeta.setCollatorStrength(strength);
Defensive patterns

Strategy: validation

Validate before calling

// validate before calling
public static void setStrengthSafe(ValueMetaBase vm, int strength) {
  if (strength < 0 || strength > 3) {
    throw new IllegalArgumentException("Collator strength must be 0-3, got " + strength);
  }
  vm.setCollatorStrength(strength);
}

Type guard

static boolean isValidCollatorStrength(Integer s) {
  return s != null && s >= 0 && s <= 3;
}

Try / catch

try {
  vm.setCollatorStrength(cfgStrength);
} catch (IllegalArgumentException e) {
  log.warn("Invalid collator strength " + cfgStrength + ", using TERTIARY");
  vm.setCollatorStrength(java.text.Collator.TERTIARY);
}

Prevention

When it happens

Trigger: Calling setCollatorStrength(n) (or the constructor overload that takes collator strength) with n < 0, n > 3, or on a value meta whose collator is set, with a strength value not accepted by java.text.Collator.

Common situations: Passing a strength read from user config without range validation; confusing Collator strength with a different library's 0–5 strength scale; off-by-one when mapping UI options.

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 pentaho/pentaho-kettle@f3058517a1 (2026-09-13). Data as JSON: /api/errors/466f4fec8de62ef6. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/org/pentaho/di/core/row/value/ValueMetaBase.java:804

   */
  @Override
  public int getCollatorStrength() {
    return collatorStrength;
  }

  /**
   * @param collatorStrength
   *          the collatorStrength to set
   */
  @Override
  public void setCollatorStrength( int collatorStrength ) throws IllegalArgumentException {
    try {
      if ( collator != null ) {
        this.collator.setStrength( collatorStrength );
        this.collatorStrength = collatorStrength;
      }
    } catch ( IllegalArgumentException e ) {
      throw new IllegalArgumentException( " : Collator strength must be an int between 0 and 3. " );
    }
  }

  /**
   * @return the sortedDescending
   */
  @Override
  public boolean isSortedDescending() {
    return sortedDescending;
  }

  /**
   * @param sortedDescending
   *          the sortedDescending to set
   */
  @Override
  public void setSortedDescending( boolean sortedDescending ) {
    this.sortedDescending = sortedDescending;

View on GitHub (pinned to f3058517a1)