What causes "TextFileOutput.Exception.FileNameNotSet" in pentaho/pentaho-kettle?

Set the File name in the Text File Output step's File tab (or via a valid ${VARIABLE} that resolves at runtime).

pentaho/pentaho-kettle · error · KettleFileException

TextFileOutput.Exception.FileNameNotSet

TextFileOutput.Exception.FileNameNotSet

Error message

TextFileOutput.Exception.FileNameNotSet

What it means

getOutputFileName computes the file to write when no row-level filename is available: with a null row it falls back to meta.getFileName(). If that step property is null (no filename configured), a KettleFileException 'TextFileOutput.Exception.FileNameNotSet' is thrown. It is a configuration validation error: the Text File Output step has no target filename at all.

Solutions

Set the File name in the Text File Output step's File tab (or via a valid ${VARIABLE} that resolves at runtime).
If using 'Include filename in field', ensure the configured FileNameField exists in the incoming row stream and rows are non-null.
When building metadata in code, call textFileOutputMeta.setFileName(...) before execution.
Validate the transformation in Spoon (Validate) or check step settings before running.

Example fix

// before (programmatic meta)
textFileOutputMeta.setFileName( null );
// after
textFileOutputMeta.setFileName( "${Internal.Transformation.Filename.Directory}/out.txt" );

Defensive patterns

Strategy: validation

Validate before calling

TextFileOutputMeta meta = (TextFileOutputMeta) stepMeta.getStepMetaInterface();
String fn = meta.getFileName();
boolean fieldMode = fn == null && meta.getFileNameField() != null;
if ( fn == null && !fieldMode ) {
  throw new IllegalStateException( "TextFileOutput step has no filename configured" );
}

Try / catch

try {
  transformation.startExecution();
} catch ( KettleFileException e ) {
  if ( "TextFileOutput.Exception.FileNameNotSet".equals( e.getMessage() )
       || ( e.getMessage() != null && e.getMessage().contains( "file name" ) ) ) {
    // set the filename in step metadata and retry
  }
}

Prevention

Always fill in the File name field (or a resolvable variable) in Text File Output
Use Spoon's transformation validation before deployment
When generating metadata in code, assert setFileName() was called before execution
If using filename-in-field mode, confirm the field exists in the row stream and meta.getFileName() fallback is set for null rows

When it happens

Trigger: initOutput or writeRowToFile calls getOutputFileName(null) and meta.getFileName() returns null — i.e. the 'File name' field is empty in the step dialog and no filename-in-field mode supplied a value.

Common situations: Copying a step between transformations where the filename variable was dropped; a template transformation with the filename field left blank; programmatic step-metadata construction (StepMeta with TextFileOutputMeta) that never calls setFileName; filename supplied only via a field while no rows arrive to set it and meta.getFileName() is null.

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/steps/textfileoutput/TextFileOutput.java:249

      data.fos = fileStreams.getFileOutputStream();
      data.out = fileStreams.getCompressedOutputStream();
      data.writer = fileStreams.getBufferedOutputStream();
    } catch ( KettleException ke ) {
      throw ke;
    } catch ( Exception e ) {
      throw new KettleException( "Error opening new file : " + e.toString() );
    }
  }

  public String getOutputFileName( Object[] row ) throws KettleException {
    String filename = null;
    if ( row == null ) {
      if ( data.writer != null ) {
        filename = data.getFileStreamsCollection().getLastFileName( );
      } else {
        filename = meta.getFileName();
        if ( filename == null ) {
          throw new KettleFileException( BaseMessages.getString( PKG, "TextFileOutput.Exception.FileNameNotSet" ) );
        }
        filename = buildFilename( environmentSubstitute( filename ), true );
      }
    } else {
      data.fileNameFieldIndex = getInputRowMeta().indexOfValue( meta.getFileNameField() );
      if ( data.fileNameFieldIndex < 0 ) {
        throw new KettleStepException( BaseMessages.getString( PKG, "TextFileOutput.Exception.FileNameFieldNotFound", meta.getFileNameField() ) );
      }
      data.fileNameMeta = getInputRowMeta().getValueMeta( data.fileNameFieldIndex );
      data.fileName = data.fileNameMeta.getString( row[data.fileNameFieldIndex] );

      if ( data.fileName == null ) {
        throw new KettleFileException( BaseMessages.getString( PKG, "TextFileOutput.Exception.FileNameNotSet" ) );
      }

      filename = buildFilename( environmentSubstitute( data.fileName ), true );
    }
    return filename;

View on GitHub (pinned to f3058517a1)