{"record":{"id":"0a44157c239f6fb0","repo":"pentaho/pentaho-kettle","slug":"could-not-delete-stale-file-buildfilename","errorCode":null,"errorMessage":"Could not delete stale file \" + buildFilename","messagePattern":"Could not delete stale file \" \\+ buildFilename","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"plugins/excel/core/src/main/java/org/pentaho/di/trans/steps/excelwriter/ExcelWriterStep.java","lineNumber":682,"sourceCode":"      data.clearStyleCache( numOfFields );\n\n      // build new filename\n      String buildFilename = buildFilename( data.splitnr );\n\n      data.file = KettleVFS.getInstance( getTransMeta().getBowl() ).getFileObject( buildFilename, getTransMeta() );\n\n      if ( log.isDebug() ) {\n        logDebug( BaseMessages.getString( PKG, \"ExcelWriterStep.Log.OpeningFile\", buildFilename ) );\n      }\n\n      // determine whether existing file must be deleted\n      if ( data.file.exists() && data.createNewFile ) {\n        if ( !data.file.delete() ) {\n          if ( log.isBasic() ) {\n            logBasic( BaseMessages.getString( PKG, \"ExcelWriterStep.Log.CouldNotDeleteStaleFile\", buildFilename ) );\n          }\n          setErrors( 1 );\n          throw new KettleException( \"Could not delete stale file \" + buildFilename );\n        }\n      }\n\n      // adding filename to result\n      if ( meta.isAddToResultFiles() ) {\n        // Add this to the result file names...\n        ResultFile resultFile =\n            new ResultFile( ResultFile.FILE_TYPE_GENERAL, data.file, getTransMeta().getName(), getStepname() );\n        resultFile.setComment( \"This file was created with an Excel writer step by Pentaho Data Integration\" );\n        addResultFile( resultFile );\n      }\n\n      boolean appendingToSheet;\n      if ( data.file.exists() ) {\n        appendingToSheet = true;\n      } else {\n        createFile();\n        appendingToSheet = false;","sourceCodeStart":664,"sourceCodeEnd":700,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/plugins/excel/core/src/main/java/org/pentaho/di/trans/steps/excelwriter/ExcelWriterStep.java#L664-L700","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Close the output file if it is open in Excel or another application","Check and clear read-only attribute / grant delete permission to the PDI user","Stop processes holding a lock on the file (antivirus, indexer, previous kitchen run)","Delete the file manually before rerunning, or disable 'Create new file at start' if appending is intended"],"exampleFix":"// before: file locked by Excel -> delete() fails\n// after (pre-check in a prior step / shell): remove stale file with retry\nif (new File(filename).delete()) { /* ok */ } else { throw new IOException(\"Close any program using \" + filename); }","handlingStrategy":"validation","validationCode":"File f = new File(filename);\nif (f.exists() && createNewFile) {\n  boolean deleted = f.delete();\n  if (!deleted) throw new IllegalStateException(\n      \"Cannot delete \" + f + \": close any program using it and check permissions\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Close the output file in Excel before rerunning","Remove read-only attributes; grant PDI user delete rights on the folder","On Windows, watch for antivirus/indexer handle retention","Disable 'Create new file at start' when appending is intended"],"tags":["excel","file-delete","file-locked","permissions","kettle"],"backgroundTag":"file-write-permission-denied","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"}