pentaho/pentaho-kettle · error · KettleException

FileLocked.Exception.CouldnotFindField

FileLocked.Exception.CouldnotFindField

Error message

FileLocked.Exception.CouldnotFindField

What it means

After locating the configured dynamic filename field, FileLocked caches its index in the previous row's metadata. If indexOfValue() returns -1 the configured field does not exist in the incoming row stream, so the step cannot determine which file to check and throws this KettleException.

Solutions

  1. Verify the field name configured in the step matches exactly (case-sensitive) a field in the incoming stream - use 'Get fields' in the dialog.
  2. Add or fix the upstream step so it outputs the filename field (e.g. Text File Input, Get File Names, JavaScript).
  3. Preview the previous step to confirm the actual output field names, then re-select the field in the FileLocked dialog.

Example fix

// before
meta.setDynamicFilenameField("filenames"); // upstream field is actually 'filename'
// after
meta.setDynamicFilenameField("filename");
Defensive patterns

Strategy: validation

Validate before calling

// Confirm the field exists in the incoming stream before execution:
String field = meta.getDynamicFilenameField();
if (prevRowMeta.indexOfValue(field) < 0) {
  throw new IllegalStateException("Field '" + field + "' not present in previous step output");
}

Try / catch

try {
  trans.execute(null);
} catch (KettleException e) {
  if (e.getMessage().contains("CouldnotFindField")) {
    log.error("Check FileLocked step field name against upstream output", e);
  }
  throw e;
}

Prevention

When it happens

Trigger: processRow() on the first row: meta.getDynamicFilenameField() is non-empty but data.previousRowMeta.indexOfValue(...) returns -1 because the upstream step does not emit a field with that exact name.

Common situations: Typo or case mismatch between the configured field name and the actual output field; an upstream step was renamed or removed; field is only produced conditionally; connecting the step to the wrong hop.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/filelocked/FileLocked.java:86

      data.NrPrevFields = data.previousRowMeta.size();
      data.outputRowMeta = data.previousRowMeta;
      meta.getFields( getTransMeta().getBowl(), data.outputRowMeta, getStepname(), null, null, this, repository,
        metaStore );

      // Check is filename field is provided
      if ( Utils.isEmpty( meta.getDynamicFilenameField() ) ) {
        logError( BaseMessages.getString( PKG, "FileLocked.Error.FilenameFieldMissing" ) );
        throw new KettleException( BaseMessages.getString( PKG, "FileLocked.Error.FilenameFieldMissing" ) );
      }

      // cache the position of the field
      if ( data.indexOfFileename < 0 ) {
        data.indexOfFileename = data.previousRowMeta.indexOfValue( meta.getDynamicFilenameField() );
        if ( data.indexOfFileename < 0 ) {
          // The field is unreachable !
          logError( BaseMessages.getString( PKG, "FileLocked.Exception.CouldnotFindField" )
            + "[" + meta.getDynamicFilenameField() + "]" );
          throw new KettleException( BaseMessages.getString( PKG, "FileLocked.Exception.CouldnotFindField", meta
            .getDynamicFilenameField() ) );
        }
      }
    } // End If first

    try {
      // get filename
      String filename = data.previousRowMeta.getString( r, data.indexOfFileename );
      if ( !Utils.isEmpty( filename ) ) {
        // Check if file
        LockFile locked = new LockFile( getTransMeta().getBowl(), filename );
        FileLocked = locked.isLocked();

        // add filename to result filenames?
        if ( meta.addResultFilenames() ) {
          // Add this to the result file names...
          ResultFile resultFile =
            new ResultFile( ResultFile.FILE_TYPE_GENERAL, KettleVFS.getInstance( getTransMeta().getBowl() )

View on GitHub (pinned to f3058517a1)