pentaho/pentaho-kettle · error · KettleException

ZipFile.Error.SourceFilenameFieldMissing

Error message

ZipFile.Error.SourceFilenameFieldMissing

What it means

Thrown in ZipFile.processRow() during initialization when the 'source filename field' (dynamic source file name) is not configured in the step metadata. The Zip File step zips files whose names come from an incoming stream field, so this field must be set; Utils.isEmpty treats null or empty string as missing.

Solutions

  1. Open the Zip File step dialog and set the 'Source filename fieldname' to an incoming String field containing file paths.
  2. Ensure the upstream step actually supplies a filename field and map its name exactly in the dialog.
  3. If migrating/copied transformations, re-open and re-save the step to regenerate missing metadata attributes.
  4. Validate the saved .ktr XML contains the dynamic source filename field tag before deploying.

Example fix

// before: metadata without source field configured
zipFileMeta.setDynamicSourceFileNameField( null );

// after: set the field coming from the previous step
zipFileMeta.setDynamicSourceFileNameField( "filename" ); // must match an incoming field
Defensive patterns

Strategy: validation

Validate before calling

if ( Utils.isEmpty( zipFileMeta.getDynamicSourceFileNameField() ) ) {
  throw new KettleException( "Zip File step requires 'Source filename fieldname' to be set" );
}

Try / catch

try {
  trans.execute( null ); // run transformation containing the Zip File step
} catch ( KettleException e ) {
  if ( e.getMessage() != null && e.getMessage().contains( "SourceFilenameFieldMissing" ) ) {
    logError( "Configure the Zip File step's source filename field and re-run", e );
  }
}

Prevention

When it happens

Trigger: First call to processRow() after getFields(): if meta.getDynamicSourceFileNameField() is null/empty, the KettleException 'ZipFile.Error.SourceFilenameFieldMissing' is thrown and the step fails to start.

Common situations: Step dialog saved without selecting the 'Source filename fieldname', transformation XML or repository entry missing that attribute (hand-edited or partial migration), field option reset after upgrading a transformation.

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/zipfile/ZipFile.java:86

    data = (ZipFileData) sdi;

    Object[] r = getRow(); // Get row from input rowset & set row busy!
    if ( r == null ) { // no more input to be expected...

      setOutputDone();
      return false;
    }

    if ( first ) {
      first = false;

      data.outputRowMeta = getInputRowMeta().clone();
      meta.getFields( getTransMeta().getBowl(), data.outputRowMeta, getStepname(), null, null, this,
        getTrans().getRepository(), getTrans().getMetaStore() );

      // Check is source filename field is provided
      if ( Utils.isEmpty( meta.getDynamicSourceFileNameField() ) ) {
        throw new KettleException( BaseMessages.getString( PKG, "ZipFile.Error.SourceFilenameFieldMissing" ) );
      }
      // Check is target filename field is provided
      if ( Utils.isEmpty( meta.getDynamicTargetFileNameField() ) ) {
        throw new KettleException( BaseMessages.getString( PKG, "ZipFile.Error.TargetFilenameFieldMissing" ) );
      }

      // cache the position of the source filename field
      if ( data.indexOfSourceFilename < 0 ) {
        data.indexOfSourceFilename = getInputRowMeta().indexOfValue( meta.getDynamicSourceFileNameField() );
        if ( data.indexOfSourceFilename < 0 ) {
          // The field is unreachable !
          throw new KettleException( BaseMessages.getString( PKG, "ZipFile.Exception.CouldnotFindField", meta
            .getDynamicSourceFileNameField() ) );
        }
      }

      data.indexOfZipFilename = getInputRowMeta().indexOfValue( meta.getDynamicTargetFileNameField() );
      if ( data.indexOfZipFilename < 0 ) {

View on GitHub (pinned to f3058517a1)