pentaho/pentaho-kettle · error · KettleXMLException

ZipFileMeta.Exception.UnableToReadStepInfo

Error message

ZipFileMeta.Exception.UnableToReadStepInfo

What it means

ZipFileMeta.loadXML wraps any Exception thrown while reading the step's settings from a .ktr XML node into this KettleXMLException. It means the step metadata could not be deserialized from the transformation file, so the transformation cannot load this step.

Solutions

  1. Inspect the chained cause 'e' for the exact parsing problem and the offending .ktr location.
  2. Open the .ktr in the Spoon GUI; if it fails, recreate the ZipFile step and re-enter its settings.
  3. Recover the transformation from version control or a backup copy.
  4. Align PDI versions — export/import between mismatched Pentaho versions can change step XML layout.

Example fix

// before: hand-edited step node missing required tags
<zip_file><sourcefilenamefield>filename</sourcefilenamefield></zip_file>
// after: restore the full step XML via Spoon save, not manual editing
<zip_file>
  <sourcefilenamefield>filename</sourcefilenamefield>
  <sourcemultiplefiles>N</sourcemultiplefiles>
  ...
</zip_file>
Defensive patterns

Strategy: try-catch

Validate before calling

Document doc = XMLHandler.loadXMLFile(new File(ktrPath));
if (XMLHandler.getSubNode(XMLHandler.getFirstSubNode(doc, "transformation"), "step") == null) {
    throw new IllegalStateException("No steps in " + ktrPath);
}

Try / catch

try {
    transMeta = new TransMeta(ktrPath);
} catch (KettleXMLException e) {
    if (e.getMessage().contains("UnableToReadStepInfo")) { /* restore/recreate step metadata */ }
    throw e;
}

Prevention

When it happens

Trigger: loadXML -> readData encounters malformed or unexpected XML in a <zip_file> step node — e.g. XMLHandler.getTagValue throwing on a corrupt or hand-edited .ktr file, or incompatible/older step XML produced by a different PDI version.

Common situations: Corrupt or truncated .ktr after a bad save or merge conflict; hand-editing transformation XML; opening a transformation exported from a much older/newer Pentaho version whose step XML schema changed.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/zipfile/ZipFileMeta.java:238

    parentStepMeta.getParentTransMeta().getNamedClusterEmbedManager().registerUrl( baseFolderField );
    return retval.toString();
  }

  private void readData( Node stepnode ) throws KettleXMLException {
    try {
      sourcefilenamefield = XMLHandler.getTagValue( stepnode, "sourcefilenamefield" );
      targetfilenamefield = XMLHandler.getTagValue( stepnode, "targetfilenamefield" );
      baseFolderField = XMLHandler.getTagValue( stepnode, "baseFolderField" );
      operationType =
        getOperationTypeByCode( Const.NVL( XMLHandler.getTagValue( stepnode, "operation_type" ), "" ) );
      addresultfilenames = "Y".equalsIgnoreCase( XMLHandler.getTagValue( stepnode, "addresultfilenames" ) );
      overwritezipentry = "Y".equalsIgnoreCase( XMLHandler.getTagValue( stepnode, "overwritezipentry" ) );
      createparentfolder = "Y".equalsIgnoreCase( XMLHandler.getTagValue( stepnode, "createparentfolder" ) );
      keepsourcefolder = "Y".equalsIgnoreCase( XMLHandler.getTagValue( stepnode, "keepsourcefolder" ) );
      movetofolderfield = XMLHandler.getTagValue( stepnode, "movetofolderfield" );

    } catch ( Exception e ) {
      throw new KettleXMLException( BaseMessages.getString( PKG, "ZipFileMeta.Exception.UnableToReadStepInfo" ), e );
    }
  }

  public void readRep( Repository rep, IMetaStore metaStore, ObjectId id_step, List<DatabaseMeta> databases ) throws KettleException {
    try {
      sourcefilenamefield = rep.getStepAttributeString( id_step, "sourcefilenamefield" );
      targetfilenamefield = rep.getStepAttributeString( id_step, "targetfilenamefield" );
      baseFolderField = rep.getStepAttributeString( id_step, "baseFolderField" );
      operationType =
        getOperationTypeByCode( Const.NVL( rep.getStepAttributeString( id_step, "operation_type" ), "" ) );
      addresultfilenames = rep.getStepAttributeBoolean( id_step, "addresultfilenames" );
      overwritezipentry = rep.getStepAttributeBoolean( id_step, "overwritezipentry" );
      createparentfolder = rep.getStepAttributeBoolean( id_step, "createparentfolder" );
      keepsourcefolder = rep.getStepAttributeBoolean( id_step, "keepsourcefolder" );
      movetofolderfield = rep.getStepAttributeString( id_step, "movetofolderfield" );

    } catch ( Exception e ) {
      throw new KettleException( BaseMessages.getString(

View on GitHub (pinned to f3058517a1)