pentaho/pentaho-kettle · error · KettleValueException

API coding error: please specify the conversion metadata…

Error message

API coding error: please specify the conversion metadata before attempting to convert value " + name

What it means

An API usage guard thrown by ValueMetaTimestamp.convertDataUsingConversionMetaData when conversionMetadata has not been set on the value meta before calling it. The message names the field and states the conversion metadata must be specified first.

Solutions

Call valueMeta.setConversionMetadata(...) before converting
Derive the conversion meta from the source layout/meta instead of constructing an empty ValueMetaTimestamp
Use convertData or convertDataFromString if you have explicit source metadata

Example fix

// before
ValueMetaInterface vm = new ValueMetaTimestamp("ts");
Object v = vm.convertDataUsingConversionMetaData(data);
// after
vm.setConversionMetadata(sourceMeta.clone());
Object v = vm.convertDataUsingConversionMetaData(data);

Defensive patterns

Strategy: validation

Validate before calling

if (valueMeta.getConversionMetadata() == null) {
  throw new IllegalStateException("Call setConversionMetadata() before convertDataUsingConversionMetaData() on field " + valueMeta.getName());
}

Try / catch

try {
  converted = vm.convertDataUsingConversionMetaData(data);
} catch (KettleValueException e) {
  vm.setConversionMetadata(sourceMeta.clone());
  converted = vm.convertDataUsingConversionMetaData(data);
}

Prevention

Initialize conversion metadata immediately after constructing the value meta
Clone source metadata rather than building empty ValueMetaTimestamp
Prefer convertData with explicit source meta when both metas are known

When it happens

Trigger: Calling convertDataUsingConversionMetaData(data) on a fresh ValueMetaTimestamp without first calling setConversionMetadata(...). This is a programming contract violation, not a data problem.

Common situations: Custom transform/plugin code copying data between streams using conversion metadata (e.g. reading external schemas) but forgetting to initialize it from the layout.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

Thrown at core/src/main/java/org/pentaho/di/core/row/value/ValueMetaTimestamp.java:545

  public void setPreparedStatementValue( DatabaseMeta databaseMeta, PreparedStatement preparedStatement, int index,
                                         Object data ) throws KettleDatabaseException {

    try {
      if ( data != null ) {
        preparedStatement.setTimestamp( index, getTimestamp( data ) );
      } else {
        preparedStatement.setNull( index, java.sql.Types.TIMESTAMP );
      }
    } catch ( Exception e ) {
      throw new KettleDatabaseException( toStringMeta() + " : Unable to set value on prepared statement on index "
        + index, e );
    }
  }

  @Override
  public Object convertDataUsingConversionMetaData( Object data2 ) throws KettleValueException {
    if ( conversionMetadata == null ) {
      throw new KettleValueException(
        "API coding error: please specify the conversion metadata before attempting to convert value " + name );
    }

    return super.convertDataUsingConversionMetaData( data2 );
  }

  @Override
  public byte[] getBinaryString( Object object ) throws KettleValueException {

    if ( object == null ) {
      return null;
    }

    if ( isStorageBinaryString() && identicalFormat ) {
      return (byte[]) object; // shortcut it directly for better performance.
    }

    switch ( storageType ) {

View on GitHub (pinned to f3058517a1)