pentaho/pentaho-kettle · error · KettleValueException

<toString()> : couldn't convert String to Integer : value…

Error message

<toString()> : couldn't convert String to Integer : value Out of Range [<string>]. Change the destination data type or round to the nearest value possible for Integer by setting property KETTLE_IGNORE_OUT_OF_RANGE_EXCEPTION to "Y".

What it means

Thrown by ValueMetaBase.convertStringToInteger when a parsed number's Double value falls outside Long.MIN_VALUE/MAX_VALUE range and the KETTLE_IGNORE_OUT_OF_RANGE_EXCEPTION property is not set to 'Y'. Pentaho Kettle (PDI) refuses to silently truncate the integer, so conversion aborts with a KettleValueException. The value name is prefixed by toString() so you can identify which field failed.

Solutions

Fix the source value or widen the field type to BigNumber (TYPE_NUMBER/TYPE_BIGNUMBER) so no Long truncation is needed.
Set JVM system property -DKETTLE_IGNORE_OUT_OF_RANGE_EXCEPTION=Y to truncate to the nearest representable value instead of throwing.
Pre-validate/pre-process the string in a JavaScript/UDJE step to clamp values into Long range before the conversion.
Use a Select Values step to change the field's metadata to String or BigNumber before the row is converted to Integer.

Example fix

// before: field typed as Integer, value '99999999999999999999' overflows
// after: change value meta to BigNumber in a Select Values / Java Script step
ValueMetaInterface vmi = new ValueMetaNumber("amount");
vmi.setConversionMask("#"); // or declare the column as BigNumber in the CSV input step
// alternative: JVM arg
// -DKETTLE_IGNORE_OUT_OF_RANGE_EXCEPTION=Y

Defensive patterns

Strategy: validation

Validate before calling

double d = Double.parseDouble(s);
if (d < Long.MIN_VALUE || d > Long.MAX_VALUE) {
    throw new IllegalArgumentException("Value out of Long/Integer range: " + s);
}

Type guard

static boolean fitsInLong(double d) { return d >= Long.MIN_VALUE && d <= Long.MAX_VALUE && !Double.isNaN(d); }

Try / catch

try {
    long v = valueMeta.getInteger(s);
} catch (KettleValueException e) {
    // fall back to BigDecimal storage
    BigDecimal bd = valueMeta.getBigNumber(s);
}

Prevention

Type wide numeric columns as BigNumber instead of Integer in input steps
Set -DKETTLE_IGNORE_OUT_OF_RANGE_EXCEPTION=Y when truncation is acceptable
Validate numeric ranges at the boundary (file/db input) before conversion

When it happens

Trigger: convertStringToInteger(String) called via ValueMeta.getString→Integer conversion (or convertRowToNativeType) where the string parses as a Double exceeding Long range, e.g. '9223372036854775808' or '1E30', and system property KETTLE_IGNORE_OUT_OF_RANGE_EXCEPTION != 'Y'.

Common situations: Reading text/CSV files whose numeric column overflows Long; loading data from systems with wider numeric types (e.g. Oracle NUMBER, big counters) into a Kettle Integer field; scientific-notation strings like '1e25'.

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/0e02c54839188e5d. Report an issue: GitHub.

Appendix: source

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

      Number number;
      if ( lenientStringToNumber ) {
        number = getDecimalFormat( false ).parse( string );
      } else {
        ParsePosition parsePosition = new ParsePosition( 0 );
        number = getDecimalFormat( false ).parse( string, parsePosition );

        if ( parsePosition.getIndex() < string.length() ) {
          throw new KettleValueException( toString()
            + " : couldn't convert String to number : non-numeric character found at position "
            + ( parsePosition.getIndex() + 1 ) + " for value [" + string + "]" );
        }
      }

      if ( number instanceof Double && ( number.doubleValue() < Long.MIN_VALUE
        || number.doubleValue() > Long.MAX_VALUE ) ) {
        log.logBasic( "Value [" + string + "] is out of range for Integer." );
        if ( !ignoreOutOfRange ) {
          throw new KettleValueException( toString()
            + " : couldn't convert String to Integer : value Out of Range [" + string
            + "]. Change the destination data type or round to the nearest value possible for Integer by setting "
            + "property KETTLE_IGNORE_OUT_OF_RANGE_EXCEPTION to \"Y\". " );
        }
      }

      return new Long( number.longValue() );
    } catch ( Exception e ) {
      throw new KettleValueException( toString() + " : couldn't convert String to Integer", e );
    }
  }

  protected synchronized String convertBigNumberToString( BigDecimal number ) throws KettleValueException {
    if ( number == null ) {
      return null;
    }

    try {

View on GitHub (pinned to f3058517a1)