pentaho/pentaho-kettle · error · KettleException

FileLocked.Error.FilenameFieldMissing

FileLocked.Error.FilenameFieldMissing

Error message

FileLocked.Error.FilenameFieldMissing

What it means

The FileLocked step checks if a file is locked, and the name of the file can either be static or taken from an incoming row field. This error is thrown in processRow when the step's meta configuration has no 'dynamic filename field' set, so the step does not know which incoming field contains the file path to test.

Solutions

  1. Open the FileLocked step dialog and set the 'filename field' to an incoming String field containing the file path.
  2. If the file name is fixed, do not use the dynamic field option - configure the step accordingly or use a 'Get File Names'/'Text File Input' approach feeding the field.
  3. Inspect the transformation XML/repository entry to confirm the <filenamefield> tag has a non-empty value before running.

Example fix

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

Strategy: validation

Validate before calling

// Before running the transformation, verify the step config:
FileLockedMeta meta = (FileLockedMeta) transMeta.findStep("FileLocked").getStepMeta();
if (meta.getDynamicFilenameField() == null || meta.getDynamicFilenameField().isEmpty()) {
  throw new IllegalStateException("FileLocked step has no filename field configured");
}

Prevention

When it happens

Trigger: processRow() runs and Utils.isEmpty(meta.getDynamicFilenameField()) is true, i.e. the 'filename field' textbox in the FileLocked step dialog was left empty when the transformation was saved.

Common situations: Transformation exported/copied between environments loses step settings; user created the step but never opened the dialog to configure it; a repository or XML round-trip dropped the 'filenamefield' attribute (e.g. older file saved by a version without that option).

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

Appendix: source

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

      setOutputDone();
      return false;
    }

    boolean FileLocked = false;

    if ( first ) {
      first = false;
      // get the RowMeta
      data.previousRowMeta = getInputRowMeta().clone();
      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 );

View on GitHub (pinned to f3058517a1)