pentaho/pentaho-kettle · error · KettleValueException

<toString()> : couldn't convert BigNumber to String

Error message

<toString()> : couldn't convert BigNumber to String

What it means

Thrown by ValueMetaBase.convertBigNumberToString when formatting a BigDecimal with the configured DecimalFormat throws. Kettle wraps any formatting exception (bad conversion mask, illegal symbols) into a KettleValueException identifying the value via toString().

Solutions

  1. Check getCause() for the DecimalFormat error and correct setConversionMask on the field's ValueMeta.
  2. Use a standard mask such as '#.###############' or '0.00' that DecimalFormat accepts.
  3. If no special formatting is needed, clear the conversion mask (null) so Kettle uses its default BigDecimal formatting.
  4. Verify the BigDecimal itself is finite and not NaN-like input produced upstream.

Example fix

// before
vm.setConversionMask("##,##0.00### (bad)"); // invalid pattern -> format throws
// after
vm.setConversionMask("#,##0.00");
Defensive patterns

Strategy: validation

Validate before calling

try {
    new java.text.DecimalFormat(mask);
} catch (IllegalArgumentException e) {
    throw new IllegalArgumentException("Invalid conversion mask: " + mask);
}

Type guard

static boolean isValidDecimalFormat(String mask) { try { new java.text.DecimalFormat(mask); return true; } catch (IllegalArgumentException e) { return false; } }

Try / catch

try {
    String out = valueMeta.convertBigNumberToString(bd);
} catch (KettleValueException e) {
    String out = bd.toPlainString(); // fallback formatting
}

Prevention

When it happens

Trigger: convertBigNumberToString(BigDecimal) called (e.g. writing text output, converting storage) with a conversion mask/DecimalFormat that cannot format the BigDecimal — invalid mask characters, incompatible rounding settings, or a broken DecimalFormat configuration on the ValueMeta.

Common situations: A typo in setConversionMask (e.g. '###.##0,00' stray characters), reusing a non-thread-safe DecimalFormat incorrectly, or mask set for integers while value is a huge BigDecimal.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

AI-assisted analysis of pentaho/pentaho-kettle@f3058517a1 (2026-09-13). Data as JSON: /api/errors/15100ac308baf13d. Report an issue: GitHub.

Appendix: source

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

            + "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 {
      return getDecimalFormat( bigNumberFormatting ).format( number );
    } catch ( Exception e ) {
      throw new KettleValueException( toString() + " : couldn't convert BigNumber to String ", e );
    }
  }

  protected synchronized BigDecimal convertStringToBigNumber( String string ) throws KettleValueException {
    string = Const.trimToType( string, getTrimType() ); // see if trimming needs
    // to be performed before
    // conversion

    if ( Utils.isEmpty( string ) ) {
      return null;
    }

    try {
      DecimalFormat format = getDecimalFormat( bigNumberFormatting );
      Number number;
      if ( lenientStringToNumber ) {
        number = format.parse( string );
      } else {

View on GitHub (pinned to f3058517a1)