pentaho/pentaho-kettle · error · KettleException

FileLockedMeta.Exception.UnexpectedErrorReadingStepInfo

FileLockedMeta.Exception.UnexpectedErrorReadingStepInfo

Error message

FileLockedMeta.Exception.UnexpectedErrorReadingStepInfo

What it means

readRep loads the FileLocked step's settings from a Pentaho repository (getStepAttributeString/Boolean for filenamefield, resultfieldname, addresultfilenames). Any repository access failure is wrapped in a KettleException with this message, meaning the step definition could not be read from the database-backed repository.

Solutions

  1. Check repository connectivity (test the repository connection in Spoon) and that the database is running.
  2. Verify the repository schema is up to date for your Pentaho version (run the upgrade scripts).
  3. Re-save or recreate the step if its repository rows are corrupted; fall back to loading the transformation from a .ktr file.
Defensive patterns

Strategy: try-catch

Validate before calling

// Test repository connectivity before loading:
Repository rep = KettleDatabaseRepository.findRepository(...);
if (!rep.connect("user", "pass")) throw new IllegalStateException("Repository unavailable");

Try / catch

try {
  transMeta.readRep(rep, metaStore, id_step, databases);
} catch (KettleException e) {
  if (e.getMessage().contains("UnexpectedErrorReadingStepInfo")) {
    log.error("Repository read failed for step " + id_step + " - check DB connectivity/schema", e);
  }
  throw e;
}

Prevention

When it happens

Trigger: readRep(): rep.getStepAttributeString/getStepAttributeBoolean throws - repository DB unreachable, R_STEP_ATTRIBUTE table missing/corrupt, or invalid id_step.

Common situations: Repository database down or migrated; schema version mismatch after a Pentaho upgrade; broken repository connection settings; manually deleted repository rows.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

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

Appendix: source

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

  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 );
      rep.saveStepAttribute( id_transformation, id_step, "resultfieldname", resultfieldname );
      rep.saveStepAttribute( id_transformation, id_step, "addresultfilenames", addresultfilenames );
    } catch ( Exception e ) {
      throw new KettleException( BaseMessages.getString( PKG, "FileLockedMeta.Exception.UnableToSaveStepInfo" )
        + id_step, e );
    }
  }

  public void check( List<CheckResultInterface> remarks, TransMeta transMeta, StepMeta stepMeta,
    RowMetaInterface prev, String[] input, String[] output, RowMetaInterface info, VariableSpace space,
    Repository repository, IMetaStore metaStore ) {

View on GitHub (pinned to f3058517a1)