pentaho/pentaho-kettle · error · KettleException

ExcelWriterStep.Exception.MaxSheetName

ExcelWriterStep.Exception.MaxSheetName

Error message

ExcelWriterStep.Exception.MaxSheetName (localized message with sheet name)

What it means

Excel (both HSSF and XSSF) enforces a maximum sheet name length of 31 characters. prepareNextOutputFile() validates data.realSheetname before creating the workbook and throws this localized error when the configured sheet name exceeds 31 chars.

Solutions

1. Shorten the sheet name to 31 characters or fewer
2. If the sheet name comes from a field, add a substring step to truncate it before this step
3. Enable/adjust 'Sheet name source' to use a fixed short name
4. Check for accidental whitespace or suffix appending in the sheetname field mapping

Example fix

// before
String sheetName = inputData.getString("report_name_long_value");
// after
String sheetName = inputData.getString("report_name_long_value");
if (sheetName != null && sheetName.length() > 31) { sheetName = sheetName.substring(0, 31); }

String sheetName = environmentSubstitute(meta.getSheetname());
if (sheetName != null && sheetName.length() > 31) {
  throw new IllegalArgumentException("Sheet name must be <= 31 chars: " + sheetName);
}
if (sheetName != null && sheetName.matches(".*[\\\\/?*\[\]:].*")) {
  throw new IllegalArgumentException("Sheet name contains forbidden characters: " + sheetName);
}

When it happens

Trigger: Sheet name field or field-value resolution produces a string longer than 31 characters, e.g. a long field value used as sheet name via 'Sheet name defined in a field'.

Common situations: Using data values (dates with prefixes, concatenations) as sheet names; copying a sheet name from another tool that allowed longer names; filename-derived sheet names.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• ExcelWriterStep.Exception.TemplateNotFound
• At least one slave server is required to be present in…
• ChangeFileEncoding.Error.TargetFileIsEmpty
• Could not delete stale file " + buildFilename
• DynamicSQLRow.Exception.SQLFieldNameEmpty

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

Appendix: source

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

  public static void copyFile( Bowl bowl, FileObject in, FileObject out ) throws KettleException {
    try ( BufferedInputStream fis = new BufferedInputStream( KettleVFS.getInputStream( in ) );
        BufferedOutputStream fos = new BufferedOutputStream( KettleVFS.getInstance( bowl )
          .getOutputStream( out, false ) ) ) {
      byte[] buf = new byte[1024 * 1024]; // copy in chunks of 1 MB
      int i = 0;
      while ( ( i = fis.read( buf ) ) != -1 ) {
        fos.write( buf, 0, i );
      }
    } catch ( Exception e ) {
      throw new KettleException( e );
    }
  }

  public void prepareNextOutputFile() throws KettleException {
    try {
      // sheet name shouldn't exceed 31 character
      if ( data.realSheetname != null && data.realSheetname.length() > 31 ) {
        throw new KettleException(
            BaseMessages.getString( PKG, "ExcelWriterStep.Exception.MaxSheetName", data.realSheetname ) );
      }
      // clear style cache
      int numOfFields =
          meta.getOutputFields() != null && meta.getOutputFields().length > 0 ? meta.getOutputFields().length : 0;
      if ( numOfFields == 0 ) {
        numOfFields = data.inputRowMeta != null ? data.inputRowMeta.size() : 0;
      }
      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 ) );
      }

View on GitHub (pinned to f3058517a1)