{"record":{"id":"2578f4a3141ac1ba","repo":"pentaho/pentaho-kettle","slug":"api-coding-error-please-specify-the-conversion-metadata-2578f4","errorCode":null,"errorMessage":"API coding error: please specify the conversion metadata before attempting to convert value \" + name","messagePattern":"API coding error: please specify the conversion metadata before attempting to convert value \" \\+ name","errorType":"exception","errorClass":"KettleValueException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/pentaho/di/core/row/value/ValueMetaTimestamp.java","lineNumber":545,"sourceCode":"  public void setPreparedStatementValue( DatabaseMeta databaseMeta, PreparedStatement preparedStatement, int index,\n                                         Object data ) throws KettleDatabaseException {\n\n    try {\n      if ( data != null ) {\n        preparedStatement.setTimestamp( index, getTimestamp( data ) );\n      } else {\n        preparedStatement.setNull( index, java.sql.Types.TIMESTAMP );\n      }\n    } catch ( Exception e ) {\n      throw new KettleDatabaseException( toStringMeta() + \" : Unable to set value on prepared statement on index \"\n        + index, e );\n    }\n  }\n\n  @Override\n  public Object convertDataUsingConversionMetaData( Object data2 ) throws KettleValueException {\n    if ( conversionMetadata == null ) {\n      throw new KettleValueException(\n        \"API coding error: please specify the conversion metadata before attempting to convert value \" + name );\n    }\n\n    return super.convertDataUsingConversionMetaData( data2 );\n  }\n\n  @Override\n  public byte[] getBinaryString( Object object ) throws KettleValueException {\n\n    if ( object == null ) {\n      return null;\n    }\n\n    if ( isStorageBinaryString() && identicalFormat ) {\n      return (byte[]) object; // shortcut it directly for better performance.\n    }\n\n    switch ( storageType ) {","sourceCodeStart":527,"sourceCodeEnd":563,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/core/src/main/java/org/pentaho/di/core/row/value/ValueMetaTimestamp.java#L527-L563","documentation":"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.","triggerScenarios":"Calling convertDataUsingConversionMetaData(data) on a fresh ValueMetaTimestamp without first calling setConversionMetadata(...). This is a programming contract violation, not a data problem.","commonSituations":"Custom transform/plugin code copying data between streams using conversion metadata (e.g. reading external schemas) but forgetting to initialize it from the layout.","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"],"exampleFix":"// before\nValueMetaInterface vm = new ValueMetaTimestamp(\"ts\");\nObject v = vm.convertDataUsingConversionMetaData(data);\n// after\nvm.setConversionMetadata(sourceMeta.clone());\nObject v = vm.convertDataUsingConversionMetaData(data);","handlingStrategy":"validation","validationCode":"if (valueMeta.getConversionMetadata() == null) {\n  throw new IllegalStateException(\"Call setConversionMetadata() before convertDataUsingConversionMetaData() on field \" + valueMeta.getName());\n}","typeGuard":null,"tryCatchPattern":"try {\n  converted = vm.convertDataUsingConversionMetaData(data);\n} catch (KettleValueException e) {\n  vm.setConversionMetadata(sourceMeta.clone());\n  converted = vm.convertDataUsingConversionMetaData(data);\n}","preventionTips":["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"],"tags":["pdi","api-misuse","value-meta","timestamp"],"backgroundTag":"missing-required-config-field","analyzedSha":"f3058517a153da500bf4551f46d79b91bf8ec552","analyzedAt":"2026-09-13T14:04:16.340Z","contentChangedAt":"2026-09-13T14:04:16.340Z","schemaVersion":2},"datasetVersion":"2026-09-20T23:17:15.980Z"}