pentaho/pentaho-kettle · error · KettleException

Could not delete stale file " + buildFilename

Error message

Could not delete stale file " + buildFilename

What it means

When 'Create new file at start' (createNewFile) is set and an existing output file is present, prepareNextOutputFile() tries file.delete(). If the OS refuses the delete (file locked, read-only, permission denied), the step logs 'CouldNotDeleteStaleFile', sets errors, and throws this KettleException.

Solutions

1. Close the output file if it is open in Excel or another application
2. Check and clear read-only attribute / grant delete permission to the PDI user
3. Stop processes holding a lock on the file (antivirus, indexer, previous kitchen run)
4. Delete the file manually before rerunning, or disable 'Create new file at start' if appending is intended

Example fix

// before: file locked by Excel -> delete() fails
// after (pre-check in a prior step / shell): remove stale file with retry
if (new File(filename).delete()) { /* ok */ } else { throw new IOException("Close any program using " + filename); }

File f = new File(filename);
if (f.exists() && createNewFile) {
  boolean deleted = f.delete();
  if (!deleted) throw new IllegalStateException(
      "Cannot delete " + f + ": close any program using it and check permissions");
}

When it happens

Trigger: data.file.exists() is true, createNewFile is true, and File.delete() returns false: typically the file is open in Excel or held by another process, or the process lacks delete permission in the directory.

Common situations: User has last run's output open in Excel; output file is read-only or on a share where the PDI user lacks delete rights; antivirus/indexer holding a handle on the file (Windows).

Understand the failure class

Background: "Permission denied" / "Failed to write" file errors: why a library can't write its files to disk (EACCES, EPERM, ENOSPC) and how to fix them — this error's family across 43 libraries.

Related errors

• ProcessFiles.Error.CanNotDeleteFile
• AbsSecurityManager.ERROR_0005_INSUFFICIENT_PRIVELEGES
• AbsSecurityProvider.ERROR_0002_UNABLE_TO_ACCESS_IS_ALLOWED
• AbsSecurityProvider.ERROR_0003_UNABLE_TO_ACCESS_GET_ALLOWED_ACTIONS
• AccessInput.Log.RequiredNotAccessibleFilesMissing

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

Appendix: source

Thrown at plugins/excel/core/src/main/java/org/pentaho/di/trans/steps/excelwriter/ExcelWriterStep.java:682

      data.clearStyleCache( numOfFields );

      // build new filename
      String buildFilename = buildFilename( data.splitnr );

      data.file = KettleVFS.getInstance( getTransMeta().getBowl() ).getFileObject( buildFilename, getTransMeta() );

      if ( log.isDebug() ) {
        logDebug( BaseMessages.getString( PKG, "ExcelWriterStep.Log.OpeningFile", buildFilename ) );
      }

      // determine whether existing file must be deleted
      if ( data.file.exists() && data.createNewFile ) {
        if ( !data.file.delete() ) {
          if ( log.isBasic() ) {
            logBasic( BaseMessages.getString( PKG, "ExcelWriterStep.Log.CouldNotDeleteStaleFile", buildFilename ) );
          }
          setErrors( 1 );
          throw new KettleException( "Could not delete stale file " + buildFilename );
        }
      }

      // adding filename to result
      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 writer step by Pentaho Data Integration" );
        addResultFile( resultFile );
      }

      boolean appendingToSheet;
      if ( data.file.exists() ) {
        appendingToSheet = true;
      } else {
        createFile();
        appendingToSheet = false;

View on GitHub (pinned to f3058517a1)