pentaho/pentaho-kettle · error · KettleException

FileExists.Error.FilenameFieldMissing

Error message

FileExists.Error.FilenameFieldMissing

What it means

The FileExists step requires a 'filename field' name configured in its metadata: the name of the incoming row field that holds the filename to test. processRow() throws a KettleException (after logging the localized 'FilenameFieldMissing' message) when that setting is empty during the first row processing.

Solutions

  1. Open the File Exists step dialog and set the 'Filename field' to an incoming field.
  2. Verify the saved ktr/repository record contains the filenamefield attribute.
  3. Recreate the step if its metadata was corrupted by an import or upgrade.

Example fix

// before
meta.setDynamicFilenameField(null);
// after
meta.setDynamicFilenameField("filename");
Defensive patterns

Strategy: validation

Validate before calling

if (meta.getDynamicFilenameField() == null || meta.getDynamicFilenameField().isEmpty()) {
  throw new IllegalStateException("FileExists step requires a 'Filename field' setting");
}

Try / catch

try {
  trans.execute(null);
} catch (KettleException e) {
  if (e.getMessage().contains("FileExists.Error.FilenameFieldMissing")) {
    // fix step configuration in the ktr and reload
  } else { throw e; }
}

Prevention

When it happens

Trigger: Executing a FileExists step whose 'Filename field' dropdown/property was never set, detected on the first processed row.

Common situations: Step added programmatically or by copy-paste without configuring the field; a repository/XML import losing step attributes; user leaving the field blank in the dialog.

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/fileexists/FileExists.java:81

    }

    boolean fileexists = false;
    String filetype = null;

    try {
      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 tablename field is provided
        if ( Utils.isEmpty( meta.getDynamicFilenameField() ) ) {
          logError( BaseMessages.getString( PKG, "FileExists.Error.FilenameFieldMissing" ) );
          throw new KettleException( BaseMessages.getString( PKG, "FileExists.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, "FileExists.Exception.CouldnotFindField" )
              + "[" + meta.getDynamicFilenameField() + "]" );
            throw new KettleException( BaseMessages.getString( PKG, "FileExists.Exception.CouldnotFindField", meta
              .getDynamicFilenameField() ) );
          }
        }
      } // End If first

      Object[] outputRow = RowDataUtil.allocateRowData( data.outputRowMeta.size() );
      for ( int i = 0; i < data.NrPrevFields; i++ ) {
        outputRow[i] = r[i];

View on GitHub (pinned to f3058517a1)