pentaho/pentaho-kettle · error · KettleXMLException

FileLockedMeta.Exception.UnableToReadStepInfo

FileLockedMeta.Exception.UnableToReadStepInfo

Error message

FileLockedMeta.Exception.UnableToReadStepInfo

What it means

FileLockedMeta.readData parses the step's XML node ('filenamefield', 'resultfieldname', 'addresultfilenames' tags). Any exception while reading these tags (malformed XML, wrong node type) is wrapped in a KettleXMLException with this message to indicate the step's definition could not be loaded from the .ktr file.

Solutions

  1. Open the .ktr in a text editor and check the <step> XML block for the FileLocked step - fix malformed or missing tags.
  2. Re-open the transformation in Spoon; if the step fails to load, delete and re-add the FileLocked step.
  3. Restore the .ktr from version control or backup if it was truncated/corrupted.

Example fix

// before (corrupt XML)
<filenamefield><filenamefield>
// after
<filenamefield>filename</filenamefield>
Defensive patterns

Strategy: try-catch

Validate before calling

// Validate the .ktr parses before load:
Document doc = XMLHandler.loadXMLFile(new File("trans.ktr"));
if (doc == null) throw new IllegalArgumentException("trans.ktr is not valid XML");

Try / catch

try {
  TransMeta tm = new TransMeta("trans.ktr");
} catch (KettleXMLException e) {
  if (e.getMessage().contains("UnableToReadStepInfo")) {
    log.error("FileLocked step XML corrupt - inspect its <step> block", e);
  }
  throw e;
}

Prevention

When it happens

Trigger: loadXML -> readData: XMLHandler.getTagValue throws while parsing the FileLocked step node, typically because the transformation XML is corrupted, truncated, hand-edited, or the stepnode passed is not the expected step element.

Common situations: Manually edited or partially merged .ktr files; file truncated by a bad transfer or git merge conflict markers left in; loading a transformation saved by an incompatible plugin version.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/filelocked/FileLockedMeta.java:146

    }
  }

  public String getXML() {
    StringBuilder retval = new StringBuilder();

    retval.append( "    " + XMLHandler.addTagValue( "filenamefield", filenamefield ) );
    retval.append( "    " + XMLHandler.addTagValue( "resultfieldname", resultfieldname ) );
    retval.append( "    " ).append( XMLHandler.addTagValue( "addresultfilenames", addresultfilenames ) );
    return retval.toString();
  }

  private void readData( Node stepnode, List<DatabaseMeta> databases ) throws KettleXMLException {
    try {
      filenamefield = XMLHandler.getTagValue( stepnode, "filenamefield" );
      resultfieldname = XMLHandler.getTagValue( stepnode, "resultfieldname" );
      addresultfilenames = "Y".equalsIgnoreCase( XMLHandler.getTagValue( stepnode, "addresultfilenames" ) );
    } catch ( Exception e ) {
      throw new KettleXMLException(
        BaseMessages.getString( PKG, "FileLockedMeta.Exception.UnableToReadStepInfo" ), e );
    }
  }

  public void readRep( Repository rep, IMetaStore metaStore, ObjectId id_step, List<DatabaseMeta> databases ) throws KettleException {
    try {
      filenamefield = rep.getStepAttributeString( id_step, "filenamefield" );
      resultfieldname = rep.getStepAttributeString( id_step, "resultfieldname" );
      addresultfilenames = rep.getStepAttributeBoolean( id_step, "addresultfilenames" );
    } catch ( Exception e ) {
      throw new KettleException( BaseMessages.getString(
        PKG, "FileLockedMeta.Exception.UnexpectedErrorReadingStepInfo" ), e );
    }
  }

  public void saveRep( Repository rep, IMetaStore metaStore, ObjectId id_transformation, ObjectId id_step ) throws KettleException {
    try {
      rep.saveStepAttribute( id_transformation, id_step, "filenamefield", filenamefield );

View on GitHub (pinned to f3058517a1)