{"record":{"id":"cff0c91780d6addb","repo":"pentaho/pentaho-kettle","slug":"tablecompare-exception-keyfieldsnotspecified","errorCode":null,"errorMessage":"TableCompare.Exception.KeyFieldsNotSpecified","messagePattern":"TableCompare\\.Exception\\.KeyFieldsNotSpecified","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/steps/tablecompare/TableCompare.java","lineNumber":125,"sourceCode":"        throw new KettleException( BaseMessages.getString( PKG, \"TableCompare.Exception.CanNotFindField\", meta\n          .getCompareSchemaField() ) );\n      }\n\n      // Compare table\n      //\n      if ( Utils.isEmpty( meta.getCompareTableField() ) ) {\n        throw new KettleException( BaseMessages.getString( PKG, \"TableCompare.Exception.CompareTableNotSpecified\" ) );\n      }\n      data.cmpTableIndex = getInputRowMeta().indexOfValue( meta.getCompareTableField() );\n      if ( data.cmpTableIndex < 0 ) {\n        throw new KettleException( BaseMessages.getString( PKG, \"TableCompare.Exception.CanNotFindField\", meta\n          .getCompareTableField() ) );\n      }\n\n      // Key fields\n      //\n      if ( Utils.isEmpty( meta.getKeyFieldsField() ) ) {\n        throw new KettleException( BaseMessages.getString( PKG, \"TableCompare.Exception.KeyFieldsNotSpecified\" ) );\n      }\n      data.keyFieldsIndex = getInputRowMeta().indexOfValue( meta.getKeyFieldsField() );\n      if ( data.keyFieldsIndex < 0 ) {\n        throw new KettleException( BaseMessages.getString( PKG, \"TableCompare.Exception.CanNotFindField\", meta\n          .getKeyFieldsField() ) );\n      }\n\n      // Exclude fields\n      //\n      if ( Utils.isEmpty( meta.getExcludeFieldsField() ) ) {\n        throw new KettleException( BaseMessages\n          .getString( PKG, \"TableCompare.Exception.ExcludeFieldsNotSpecified\" ) );\n      }\n      data.excludeFieldsIndex = getInputRowMeta().indexOfValue( meta.getExcludeFieldsField() );\n      if ( data.excludeFieldsIndex < 0 ) {\n        throw new KettleException( BaseMessages.getString( PKG, \"TableCompare.Exception.CanNotFindField\", meta\n          .getExcludeFieldsField() ) );\n      }","sourceCodeStart":107,"sourceCodeEnd":143,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/tablecompare/TableCompare.java#L107-L143","documentation":"TableCompare requires a 'Key fields' field name to be configured; processRow() validates this with Utils.isEmpty() and throws a KettleException when the setting is blank. This message key (KeyFieldsNotSpecified) signals a missing required configuration value, not a data problem. The step needs the key-fields column to know which fields form the comparison key per row.","triggerScenarios":"meta.getKeyFieldsField() returns empty/null in processRow() — the TableCompare step dialog's 'Key fields fieldname' was never filled in (or was cleared) before the transformation ran.","commonSituations":"Building the step metadata programmatically (as in test testOutputIsMuchBiggerThanInputDoesntThrowArrayIndexOutOfBounds) and forgetting to set every field; copying an existing step but not re-configuring required fields; a partially filled dialog saved before completion.","solutions":["Open the TableCompare step dialog and enter a value for 'Key fields fieldname'.","If constructing TableCompareMeta in code, call meta.setKeyFieldsField(\"...\") with a field present in the input stream before running.","Validate all required field names (compare table, key fields, exclude fields, key description, value reference, value compare) are set before executing the transformation."],"exampleFix":"// before\nTableCompareMeta meta = new TableCompareMeta();\nmeta.setCompareTableField( \"compare_table\" ); // key fields field left unset\n// after\nmeta.setKeyFieldsField( \"key_fields\" );\nmeta.setDefault(); // fills remaining required settings","handlingStrategy":"validation","validationCode":"if ( meta.getKeyFieldsField() == null || meta.getKeyFieldsField().isEmpty() ) {\n  throw new IllegalStateException( \"TableCompare: Key fields fieldname is required\" );\n}","typeGuard":null,"tryCatchPattern":"try {\n  step.processRow();\n} catch ( KettleException e ) {\n  if ( String.valueOf( e.getLocalizedMessage() ).contains( \"KeyFieldsNotSpecified\" ) ) {\n    logError( \"Set 'Key fields fieldname' in the TableCompare dialog and rerun\" );\n  }\n  setErrors( 1 );\n  stopAll();\n}","preventionTips":["Call meta.setDefault() right after constructing TableCompareMeta programmatically.","Keep a checklist of the six required field names when building step metadata in code.","Never save a transformation with required dialog fields blank; validate before execution."],"tags":["kettle","missing-config","transform-step"],"backgroundTag":"missing-required-argument","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"}