pentaho/pentaho-kettle · error · KettleException

ExcelWriterStep.Exception.TemplateNotFound

ExcelWriterStep.Exception.TemplateNotFound

Error message

ExcelWriterStep.Exception.TemplateNotFound (localized message with template sheet name)

What it means

When 'Use template' with a template sheet is enabled, createSheet() looks up data.realTemplateSheetName in the opened template workbook. If the sheet does not exist (getSheet returns null), this localized KettleException is thrown because the output sheet is produced by cloning the template sheet.

Solutions

  1. Verify the template sheet name exactly matches a sheet in the template file (case and spaces)
  2. Open the template file and confirm the sheet exists
  3. If the sheet name comes from a field, log/inspect the resolved value at runtime
  4. Trim whitespace in the sheet name field before the step
  5. Point the template to a workbook containing the expected sheet

Example fix

// before
String templateSheet = " Sheet1"; // trailing space, getSheet returns null
// after
String templateSheet = "Sheet1"; // must exactly match the sheet in the template workbook
Defensive patterns

Strategy: validation

Validate before calling

try (FileInputStream fis = new FileInputStream(templatePath);
     Workbook wb = WorkbookFactory.create(fis)) {
  String sheetName = environmentSubstitute(meta.getTemplateSheetName()).trim();
  if (wb.getSheet(sheetName) == null) {
    throw new IllegalStateException("Template sheet not found: " + sheetName
        + "; available: " + java.util.Arrays.toString(wb.getSheetNames()));
  }
}

Prevention

When it happens

Trigger: Template sheet name field or static value does not match any sheet name in the template workbook (case-sensitive lookup via getSheet).

Common situations: Template workbook was edited and the sheet renamed; sheet name contains leading/trailing spaces; sheet name field resolves to a value that does not exist at runtime; using a template saved in another language/locale with differently named sheets.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

Appendix: source

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

    // Find last row and append accordingly
    if ( !data.createNewSheet && meta.getAppendOffset() != 0 && appendingToSheet ) {
      data.posY += meta.getAppendOffset();
    }
  }

  /**
   * Creates a new sheet
   *
   * @param replacingSheetAt
   *          Order to place sheet in, if >= 0
   * @throws KettleException
   */
  private void createSheet( int replacingSheetAt ) throws KettleException {
    if ( meta.isTemplateSheetEnabled() ) {
      Sheet ts = data.wb.getSheet( data.realTemplateSheetName );
      // if template sheet is missing, break
      if ( ts == null ) {
        throw new KettleException(
            BaseMessages.getString( PKG, "ExcelWriterStep.Exception.TemplateNotFound", data.realTemplateSheetName ) );
      }
      data.sheet = data.wb.cloneSheet( data.wb.getSheetIndex( ts ) );
      data.wb.setSheetName( data.wb.getSheetIndex( data.sheet ), data.realSheetname );
      // unhide sheet in case it was hidden
      data.wb.setSheetHidden( data.wb.getSheetIndex( data.sheet ), false );
      if ( meta.isTemplateSheetHidden() ) {
        data.wb.setSheetHidden( data.wb.getSheetIndex( ts ), true );
      }
    } else {
      // no template to use, simply create a new sheet
      data.sheet = data.wb.createSheet( data.realSheetname );
    }
    if ( replacingSheetAt > -1 ) {
      data.wb.setSheetOrder( data.sheet.getSheetName(), replacingSheetAt );
    }
  }

View on GitHub (pinned to f3058517a1)