What causes "Unable to add filename to the result" in pentaho/pentaho-kettle?

Inspect the wrapped cause exception (e.getCause()) — the message itself is generic; the real failure is inside it.

pentaho/pentaho-kettle · error · KettleException

Unable to add filename to the result

Error message

Unable to add filename to the result

What it means

ExcelOutput wraps any failure while registering the generated Excel file into the transformation's result-file list in this KettleException. After successfully writing and closing a file, addFilenameToResult creates a ResultFile and calls addResultFile; any exception there (VFS, metadata access, comment handling) is wrapped so the step fails with a uniform message.

Solutions

Inspect the wrapped cause exception (e.getCause()) — the message itself is generic; the real failure is inside it.
Verify the output file was fully written and the FileObject (data.file) is still valid/open when the step finishes.
Check transformation name and step name are set and the step runs inside a normal Trans execution context.
If the cause is VFS-related, confirm the output path is accessible and not a transient/unmounted location.
Update PDI if the cause is a known NPE in result-file handling; check the wrapped stack trace against release notes.

Example fix

// before: cause swallowed by wrapper
throw new KettleException( "Unable to add filename to the result", e );
// after: guard and log cause before wrapping
if ( data.file != null && data.file.exists() ) {
  ResultFile resultFile = new ResultFile( ResultFile.FILE_TYPE_GENERAL, data.file, getTransMeta().getName(), getStepname() );
  addResultFile( resultFile );
} else {
  logError( "Output file missing, not adding to result: " + data.realFilename );
}

Defensive patterns

Strategy: try-catch

Validate before calling

if ( data.file != null && data.file.exists() ) { /* safe to add to result */ }

Type guard

boolean isAddableToResult( org.apache.commons.vfs2.FileObject f ) { return f != null && f.exists(); }

Try / catch

try { addFilenameToResult(); } catch ( KettleException e ) { logError( "Result-file registration failed: " + e.getCause(), e ); }

Prevention

Always inspect getCause() — this wrapper hides the real failure.
Keep the output path on stable, local storage during execution.
Test the transformation end-to-end after renaming steps or transformations.

When it happens

Trigger: addFilenameToResult() throws when constructing the ResultFile or calling addResultFile() raises an exception — e.g. getTransMeta().getName() or VFS-backed data.file operations fail, or the underlying file object has been closed/disposed before this runs.

Common situations: Transformation metadata unavailable mid-execution; the VFS file handle is stale after write errors; unusual filenames/paths that break VFS resolution; failures during clustered execution where the result-files collection is in an unexpected state.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

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

Appendix: source

Thrown at plugins/excel/core/src/main/java/org/pentaho/di/trans/steps/exceloutput/ExcelOutput.java:748

          stopAll();
        }
      } else {
        return true;
      }
    }
    return false;
  }

  private void addFilenameToResult() throws KettleException {
    try {
      if ( meta.isAddToResultFiles() ) {
        // Add this to the result file names...
        ResultFile resultFile =  new ResultFile( ResultFile.FILE_TYPE_GENERAL, data.file, getTransMeta().getName(), getStepname() );
        resultFile.setComment( "This file was created with an Excel output step by Pentaho Data Integration" );
        addResultFile( resultFile );
      }
    } catch ( Exception e ) {
      throw new KettleException( "Unable to add filename to the result", e );
    }
  }

  @Override
  public void dispose( StepMetaInterface smi, StepDataInterface sdi ) {
    meta = (ExcelOutputMeta) smi;
    data = (ExcelOutputData) sdi;

    if ( data.oneFileOpened ) {
      closeFile();
    }
    if ( data.file != null ) {
      try {
        data.file.close();
        data.file = null;
      } catch ( Exception e ) {
        logDetailed( BaseMessages.getString( PKG, "ExcelOutput.Log.UnableToCloseFileDuringDispose", data.file.getPublicURIString() ), e );
      }

View on GitHub (pinned to f3058517a1)