pentaho/pentaho-kettle · error · KettleException

PropertyOutput.Log.FilenameInFieldEmpty

Error message

PropertyOutput.Log.FilenameInFieldEmpty

What it means

When the Property Output step is configured with 'filename defined in a field', the filename is taken from a stream field. On the first row, if the configured filename field (after environmentSubstitute) is null or empty, the step logs this error and throws a KettleException because it has no way to determine which file to write.

Solutions

  1. Open the Property Output dialog and set the 'filename field' to a real incoming field name.
  2. Define the referenced variable (e.g. in kettle.properties or transformation properties) so it no longer resolves to empty.
  3. Uncheck 'filename defined in a field' if you intend to use a static filename instead.
  4. Validate the setting in a transformation unit test before deployment.

Example fix

// before
<filename_in_field>true</filename_in_field>
<filename_field>${UNDEFINED_VAR}</filename_field>
// after
OUTPUT_FILE_FIELD=target_file  # kettle.properties
e.g. <filename_field>target_file</filename_field>
Defensive patterns

Strategy: validation

Validate before calling

if (propertyOutputMeta.isFileNameInField()
    && Utils.isEmpty(propertyOutputMeta.environmentSubstitute(propertyOutputMeta.getFileNameField()))) {
  throw new KettleException("Filename field name is empty; set it or disable 'filename in field'");
}

Try / catch

try {
  trans.execute(transName);
} catch (KettleException e) {
  if (String.valueOf(e.getMessage()).contains("FilenameInFieldEmpty")) {
    logError("Property Output: filename-in-field is enabled but the field name is empty/undefined");
  }
}

Prevention

When it happens

Trigger: processRow() with meta.isFileNameInField()==true and environmentSubstitute(meta.getFileNameField()) returning an empty string — i.e. 'Filename in field' is checked but the filename field name setting is blank or its variable resolves to empty (lines 87-92).

Common situations: 'Take filename from field' enabled but the field name never filled in; ${OUTPUT_FILE_FIELD} variable not defined in the environment/kettle.properties; variable typed with a typo so it resolves to empty; copying the step from another transformation without updating the variable.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/propertyoutput/PropertyOutput.java:91

      if ( data.indexOfKeyField < 0 ) {
        // The field is unreachable !
        logError( BaseMessages.getString( PKG, "PropertyOutput.Log.ErrorFindingField", meta.getKeyField() ) );
        throw new KettleException( BaseMessages.getString( PKG, "PropertyOutput.Log.ErrorFindingField", meta.getKeyField() ) );
      }

      // Let's take the index of Key field ...
      data.indexOfValueField = data.inputRowMeta.indexOfValue( meta.getValueField() );
      if ( data.indexOfValueField < 0 ) {
        // The field is unreachable !
        logError( BaseMessages.getString( PKG, "PropertyOutput.Log.ErrorFindingField", meta.getValueField() ) );
        throw new KettleException( BaseMessages.getString( PKG, "PropertyOutput.Log.ErrorFindingField", meta.getValueField() ) );
      }

      if ( meta.isFileNameInField() ) {
        String realFieldName = environmentSubstitute( meta.getFileNameField() );
        if ( Utils.isEmpty( realFieldName ) ) {
          logError( BaseMessages.getString( PKG, "PropertyOutput.Log.FilenameInFieldEmpty" ) );
          throw new KettleException( BaseMessages.getString( PKG, "PropertyOutput.Log.FilenameInFieldEmpty" ) );
        }
        data.indexOfFieldfilename = data.inputRowMeta.indexOfValue( realFieldName );
        if ( data.indexOfFieldfilename < 0 ) {
          // The field is unreachable !
          logError( BaseMessages.getString( PKG, "PropertyOutput.Log.ErrorFindingField", meta.getValueField() ) );
          throw new KettleException( BaseMessages.getString( PKG, "PropertyOutput.Log.ErrorFindingField", meta
            .getValueField() ) );
        }
      } else {
        // Let's check for filename...
        data.filename = buildFilename();
        // Check if filename is empty..
        if ( Utils.isEmpty( data.filename ) ) {
          logError( BaseMessages.getString( PKG, "PropertyOutput.Log.FilenameEmpty" ) );
          throw new KettleException( BaseMessages.getString( PKG, "PropertyOutput.Log.FilenameEmpty" ) );
        }
        openNewFile();
      }

View on GitHub (pinned to f3058517a1)