pentaho/pentaho-kettle · error · KettleException

ZipFile.Error.TargetFilenameFieldMissing

Error message

ZipFile.Error.TargetFilenameFieldMissing

What it means

Thrown in ZipFile.processRow() when the 'target filename field' (the name of the .zip file to create, taken from a stream field) is not configured. Mirrors the source-field check immediately after it: both dynamic fields are mandatory for the step to operate.

Solutions

  1. Open the Zip File step dialog and set the 'Target filename fieldname' to an incoming String field holding the zip path.
  2. Confirm the upstream step provides that field and the name matches exactly (case-sensitive).
  3. Re-open and re-save the step if metadata was migrated and the attribute went missing.
  4. Validate the transformation XML/repository entry includes the target filename field attribute before execution.

Example fix

// before: only source field configured
zipFileMeta.setDynamicSourceFileNameField( "filename" );
zipFileMeta.setDynamicTargetFileNameField( null );

// after: configure both required fields
zipFileMeta.setDynamicSourceFileNameField( "filename" );
zipFileMeta.setDynamicTargetFileNameField( "zip_filename" );
Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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

Prevention

When it happens

Trigger: First processRow() call: source filename field passes the check, but meta.getDynamicTargetFileNameField() is null/empty, raising 'ZipFile.Error.TargetFilenameFieldMissing'.

Common situations: Zip File step saved without 'Target filename fieldname' selected, metadata lost during copy/migration of step XML, field setting cleared by a script or template that only set the source field.

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

Appendix: source

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

      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 ) {
        // The field is unreachable !
        throw new KettleException( BaseMessages.getString( PKG, "ZipFile.Exception.CouldnotFindField", meta
          .getDynamicTargetFileNameField() ) );
      }

View on GitHub (pinned to f3058517a1)