pentaho/pentaho-kettle · error · KettleException

Template Format Mismatch: Template has extension: " +…

Error message

Template Format Mismatch: Template has extension: " + templateExt + ", but output file has extension: " + meta.getExtension() + ". Template and output file must share the same format!

What it means

When templates are enabled, createFile() resolves the template file's extension via VFS and compares it (case-insensitively) with the configured output extension (meta.getExtension()). POI cannot mix HSSF (xls) and XSSF (xlsx), so a mismatch between template format and output format throws this descriptive KettleException.

Solutions

Set the step's Extension option to match the template file's actual extension
Convert the template to the desired format (open in Excel, Save As) so extensions agree
Verify the template file at data.realTemplateFileName really has the extension you expect (not a renamed file with wrong content)

Example fix

// before: template = report.xls, step Extension = xlsx
meta.setExtension("xlsx");
// after: match the template format
meta.setExtension("xls"); // or convert report.xls to report.xlsx

Defensive patterns

Strategy: validation

Validate before calling

String templateExt = KettleVFS.getInstance(bowl)
    .getFileObject(templatePath).getName().getExtension();
String outputExt = meta.getExtension();
if (!outputExt.equalsIgnoreCase(templateExt)) {
  throw new IllegalArgumentException("Extension mismatch: template=." + templateExt + " output=." + outputExt);
}

Prevention

Set Extension to match the template's real extension
Convert templates with Excel Save As instead of renaming
Audit template+extension pairs when reusing step metadata across transformations

When it happens

Trigger: Template file has extension xls but output extension is set to xlsx (or vice versa) while 'Use template' is enabled.

Common situations: Copying a .xls template but leaving Extension dropdown at xlsx; renaming an xls to xlsx instead of converting; switching template files without updating the extension setting.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

Appendix: source

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

  }

  /**
   * Creates a new Excel file
   */
  private void createFile() throws KettleException, IOException {

    if ( meta.isCreateParentFolders() && !data.file.getParent().exists() ) {
      data.file.getParent().createFolder();
    }

    // if template file is enabled
    if ( meta.isTemplateEnabled() ) {
      // handle template case (must have same format)
      // ensure extensions match
      String templateExt = KettleVFS.getInstance( getTransMeta().getBowl() )
        .getFileObject( data.realTemplateFileName ).getName().getExtension();
      if ( !meta.getExtension().equalsIgnoreCase( templateExt ) ) {
        throw new KettleException(
            "Template Format Mismatch: Template has extension: " + templateExt + ", but output file has extension: "
                + meta.getExtension() + ". Template and output file must share the same format!" );
      }

      if ( KettleVFS.getInstance( getTransMeta().getBowl() ).getFileObject( data.realTemplateFileName ).exists() ) {
        // if the template exists just copy the template in place
        copyFile( getTransMeta().getBowl(), KettleVFS.getInstance( getTransMeta().getBowl() )
          .getFileObject( data.realTemplateFileName, getTransMeta() ), data.file );
      } else {
        // template is missing, log it and get out
        if ( log.isBasic() ) {
          logBasic( BaseMessages.getString( PKG, "ExcelWriterStep.Log.TemplateMissing", data.realTemplateFileName ) );
        }
        setErrors( 1 );
        throw new KettleException( "Template file missing: " + data.realTemplateFileName );
      }
    } else {
      // handle fresh file case, just create a fresh workbook

View on GitHub (pinned to f3058517a1)