{"record":{"id":"9fd2b054ebeca768","repo":"pentaho/pentaho-kettle","slug":"textfileoutput-exception-filenamenotset","errorCode":"TextFileOutput.Exception.FileNameNotSet","errorMessage":"TextFileOutput.Exception.FileNameNotSet","messagePattern":"TextFileOutput\\.Exception\\.FileNameNotSet","errorType":"exception","errorClass":"KettleFileException","httpStatus":null,"severity":"error","filePath":"engine/src/main/java/org/pentaho/di/trans/steps/textfileoutput/TextFileOutput.java","lineNumber":249,"sourceCode":"      data.fos = fileStreams.getFileOutputStream();\n      data.out = fileStreams.getCompressedOutputStream();\n      data.writer = fileStreams.getBufferedOutputStream();\n    } catch ( KettleException ke ) {\n      throw ke;\n    } catch ( Exception e ) {\n      throw new KettleException( \"Error opening new file : \" + e.toString() );\n    }\n  }\n\n  public String getOutputFileName( Object[] row ) throws KettleException {\n    String filename = null;\n    if ( row == null ) {\n      if ( data.writer != null ) {\n        filename = data.getFileStreamsCollection().getLastFileName( );\n      } else {\n        filename = meta.getFileName();\n        if ( filename == null ) {\n          throw new KettleFileException( BaseMessages.getString( PKG, \"TextFileOutput.Exception.FileNameNotSet\" ) );\n        }\n        filename = buildFilename( environmentSubstitute( filename ), true );\n      }\n    } else {\n      data.fileNameFieldIndex = getInputRowMeta().indexOfValue( meta.getFileNameField() );\n      if ( data.fileNameFieldIndex < 0 ) {\n        throw new KettleStepException( BaseMessages.getString( PKG, \"TextFileOutput.Exception.FileNameFieldNotFound\", meta.getFileNameField() ) );\n      }\n      data.fileNameMeta = getInputRowMeta().getValueMeta( data.fileNameFieldIndex );\n      data.fileName = data.fileNameMeta.getString( row[data.fileNameFieldIndex] );\n\n      if ( data.fileName == null ) {\n        throw new KettleFileException( BaseMessages.getString( PKG, \"TextFileOutput.Exception.FileNameNotSet\" ) );\n      }\n\n      filename = buildFilename( environmentSubstitute( data.fileName ), true );\n    }\n    return filename;","sourceCodeStart":231,"sourceCodeEnd":267,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/engine/src/main/java/org/pentaho/di/trans/steps/textfileoutput/TextFileOutput.java#L231-L267","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before (programmatic meta)\ntextFileOutputMeta.setFileName( null );\n// after\ntextFileOutputMeta.setFileName( \"${Internal.Transformation.Filename.Directory}/out.txt\" );","handlingStrategy":"validation","validationCode":"TextFileOutputMeta meta = (TextFileOutputMeta) stepMeta.getStepMetaInterface();\nString fn = meta.getFileName();\nboolean fieldMode = fn == null && meta.getFileNameField() != null;\nif ( fn == null && !fieldMode ) {\n  throw new IllegalStateException( \"TextFileOutput step has no filename configured\" );\n}","typeGuard":null,"tryCatchPattern":"try {\n  transformation.startExecution();\n} catch ( KettleFileException e ) {\n  if ( \"TextFileOutput.Exception.FileNameNotSet\".equals( e.getMessage() )\n       || ( e.getMessage() != null && e.getMessage().contains( \"file name\" ) ) ) {\n    // set the filename in step metadata and retry\n  }\n}","preventionTips":["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"],"tags":["kettle","pdi","configuration","missing-filename"],"backgroundTag":"missing-required-config-field","analyzedSha":"f3058517a153da500bf4551f46d79b91bf8ec552","analyzedAt":"2026-09-13T14:04:16.340Z","contentChangedAt":"2026-09-13T14:04:16.340Z","schemaVersion":2},"datasetVersion":"2026-09-20T23:17:15.980Z"}