pentaho/pentaho-kettle · error · KettleException

Error opening new file (logged), KettleException( e )

Error message

Error opening new file (logged), KettleException( e )

What it means

The generic catch block of prepareNextOutputFile(): any exception while opening the new output Excel workbook (not IOException/POIXMLException, which get their own handler) is logged as 'Error opening new file', increments the step error count, and is rethrown as KettleException.

Solutions

  1. Read the logged stack trace for the root cause
  2. Increase the JVM heap (-Xmx) when opening large XLSX files
  3. If appending to an existing file, verify it opens correctly in Excel and matches the extension
  4. Upgrade POI/Kettle version if the trace indicates a POI bug

Example fix

// before: opening a huge xlsx in append mode with small heap
// after: increase heap in kettle script
# spoon.bat / kitchen.sh
-Xmx4096m
Defensive patterns

Strategy: try-catch

Validate before calling

File target = new File(filename);
if (target.isDirectory()) throw new IllegalStateException("Output path is a directory");
if (!target.getParentFile().canWrite()) throw new IllegalStateException("No write access: " + target.getParent());
if (target.length() > 100_000_000L && append) throw new IllegalStateException("Append target too large for heap");

Try / catch

try { writer.prepareNextOutputFile(); }
catch (KettleException e) {
  logError("Failed to open output: " + e.getCause(), e);
  setErrors(1);
  throw e; // fail the transformation; partial file should be inspected
}

Prevention

When it happens

Trigger: Non-IO failures during file open: OutOfMemoryError-like conditions via RuntimeException, InvalidFormatException variants not covered by POIXMLException, or runtime errors in workbook setup (style creation, sheet position setup).

Common situations: Heap exhaustion opening large XLSX workbooks; corrupted pre-existing append target; unexpected POI runtime exception during XSSFWorkbook construction.

Understand the failure class

Background: "open() failed", "failed to open file", "cannot create file" — what a file open error means and how to fix it — this error's family across 42 libraries.

Related errors

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

Appendix: source

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

        data.innerSheet = Optional.of( data.sheet );
        data.wb = new SXSSFWorkbook( (XSSFWorkbook) data.wb, STREAMING_WINDOW_SIZE );
        data.sheet = data.wb.getSheet( data.realSheetname );
      }

      if ( log.isDebug() ) {
        logDebug( BaseMessages.getString( PKG, "ExcelWriterStep.Log.FileOpened", buildFilename ) );
      }
      // this is the number of the new output file
      data.splitnr++;
    }  catch ( IOException | POIXMLException e ) {
        throw new KettleException( BaseMessages.getString( PKG, "ExcelInput.Log.UnsafeFileException" ) +
                e
        );
    }
    catch ( Exception e ) {
      logError( "Error opening new file", e );
      setErrors( 1 );
      throw new KettleException( e );
    }
  }

  /** Sets data.startingRow, data.startingCol, data.posX, data.posY */
  private void setSheetPosition( boolean appendingToSheet ) {
    // starting cell support
    if ( !Utils.isEmpty( data.realStartingCell ) ) {
      CellReference cellRef = new CellReference( data.realStartingCell );
      data.startingRow = cellRef.getRow();
      data.startingCol = cellRef.getCol();
    } else {
      data.startingRow = 0;
      data.startingCol = 0;
    }

    data.posX = data.startingCol;
    data.posY = data.startingRow;

View on GitHub (pinned to f3058517a1)