pentaho/pentaho-kettle · error · KettleException

PropertyOutput.Log.FilenameEmpty

Error message

PropertyOutput.Log.FilenameEmpty

What it means

PropertyOutput throws this KettleException during processRow when the resolved output filename is empty. The step computes the filename from the metadata settings (buildFilename) and refuses to proceed because it has nowhere to write properties. The message comes from the step's message bundle and is both logged and thrown, failing the transformation row processing.

Solutions

1. Open the Property Output step settings and set a non-empty filename in the File tab.
2. If the filename should come from a variable, verify the variable (e.g. ${OUT_FILE}) is defined via a Set Variables step or kettle.properties.
3. If the filename should be taken from an incoming row field, enable 'filename in field' and select the field, so this branch is skipped.
4. Wrap the transformation run in try-catch for KettleException and validate the step configuration programmatically before execution.

Example fix

// before (transformation XML / metadata)
<file><name></name></file>
// after
<file><name>/data/output/properties.properties</name></file>

String filename = stepMeta.getFileName(); // from PropertyOutputMeta
if (filename == null || filename.trim().isEmpty()) {
    throw new IllegalArgumentException("Property Output step requires a non-empty filename");
}

try {
    trans.execute(null);
    trans.waitUntilFinished();
} catch (KettleException e) {
    if (e.getMessage().contains("FilenameEmpty")) {
        // prompt user to configure the output filename
    }
}

When it happens

Trigger: processRow (first input row) calls buildFilename(); if the result is empty (Utils.isEmpty), e.g. when the 'filename' field in the step metadata is blank/only whitespace and filename-in-field is not used, the exception is thrown before openNewFile().

Common situations: Step configured in Spoon with an empty filename and no filename field; filename built purely from a variable like ${OUT_FILE} that is undefined at runtime so it resolves to empty; copying a step between transformations and losing the filename setting.

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

• It was not possible to find operation field
• It was not possible to find table
• JobEntrySyslog.DatePatternEmpty
• JobExecutor.Exception.GroupFieldNotFound
• JobExecutor.Exception.UnableToFindField

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

Appendix: source

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

        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();
      }
    } // end first

    // Get value field
    String propkey = data.inputRowMeta.getString( r, data.indexOfKeyField );
    String propvalue = data.inputRowMeta.getString( r, data.indexOfValueField );

    try {
      if ( meta.isFileNameInField() ) {
        data.filename = data.inputRowMeta.getString( r, data.indexOfFieldfilename );
        if ( Utils.isEmpty( data.filename ) ) {
          throw new KettleException( BaseMessages.getString( PKG, "PropertyOutputMeta.Log.FileNameEmty" ) );
        }
        if ( !checkSameFile() ) {
          // close previous file
          closeFile();

View on GitHub (pinned to f3058517a1)