pentaho/pentaho-kettle · error · KettleException

FileErrorHandlerMissingFiles.Exception.CouldNotCreateNonExistantFile

FileErrorHandlerMissingFiles.Exception.CouldNotCreateNonExistantFile

Error message

FileErrorHandlerMissingFiles.Exception.CouldNotCreateNonExistantFile

What it means

KettleException thrown by FileErrorHandlerMissingFiles.handleNonExistantFile() when recording a missing (non-existent) input file in the 'missing files' lineage file fails. The record of THIS_FILE_DOES_NOT_EXIST could not be written because the writer/file itself could not be created or written.

Solutions

Fix the error-handling file directory (exists, writable) — check the chained cause
Verify whether the missing input file itself is expected; adjust the file filter/wildcard
Grant the Kettle process write permission to the lineage directory
If missing files are normal, keep lineage enabled but point it to reliable local storage

Example fix

// before: lineage dir read-only
FileErrorHandlerMissingFiles("/mnt/ro/lineage", ...)
// after
FileErrorHandlerMissingFiles("/var/log/kettle/lineage", ...)

Defensive patterns

Strategy: validation

Validate before calling

// Pre-flight lineage directory before the file-input step starts
FileObject lineageDir = fsManager.resolveFile(lineageDirUri);
if (!lineageDir.exists() || !lineageDir.isWriteable()) {
  throw new IllegalStateException("Missing-file lineage dir unusable: " + lineageDirUri);
}

Try / catch

try {
  errorHandler.handleNonExistantFile(missingFile);
} catch (KettleException e) {
  log.error("Cannot record missing file " + missingFile.getName().getURI()
    + ": " + e.getMessage(), e);
  throw e;
}

Prevention

Create and test the lineage directory in deployment scripts
Re-check wildcard matches for transient/vanishing files (e.g. producer still writing)
Run Kettle as a user with write access to lineage directories

When it happens

Trigger: handleNonExistantFile(file) called by file-input steps that allow missing files; getWriter(NO_PARTS).write(...) throws — error lineage file location invalid, unwritable, or stream fails after creation.

Common situations: Wildcard file input where some matched files vanished between listing and processing; error-lineage directory misconfigured so even the missing-file record can't be written; permission issues on lineage directory.

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/0661f771f15ee6da. Report an issue: GitHub.

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/step/errorhandling/FileErrorHandlerMissingFiles.java:50

  public static final String THIS_FILE_WAS_NOT_ACCESSIBLE = BaseMessages.getString(
    PKG, "FileErrorHandlerMissingFiles.FILE_WAS_NOT_ACCESSIBLE" );

  public FileErrorHandlerMissingFiles( Date date, String destinationDirectory, String fileExtension,
    String encoding, BaseStep baseStep ) {
    super( date, destinationDirectory, fileExtension, encoding, baseStep );
  }

  public void handleLineError( long lineNr, String filePart ) {

  }

  public void handleNonExistantFile( FileObject file ) throws KettleException {
    handleFile( file );
    try {
      getWriter( NO_PARTS ).write( THIS_FILE_DOES_NOT_EXIST );
      getWriter( NO_PARTS ).write( Const.CR );
    } catch ( Exception e ) {
      throw new KettleException( BaseMessages.getString(
        PKG, "FileErrorHandlerMissingFiles.Exception.CouldNotCreateNonExistantFile" )
        + file.getName().getURI(), e );
    }
  }

  public void handleNonAccessibleFile( FileObject file ) throws KettleException {
    handleFile( file );
    try {
      getWriter( NO_PARTS ).write( THIS_FILE_WAS_NOT_ACCESSIBLE );
      getWriter( NO_PARTS ).write( Const.CR );
    } catch ( Exception e ) {
      throw new KettleException( BaseMessages.getString(
        PKG, "FileErrorHandlerMissingFiles.Exception.CouldNotCreateNonAccessibleFile" )
        + file.getName().getURI(), e );
    }
  }

}

View on GitHub (pinned to f3058517a1)