{"record":{"id":"d26a5ef2c06458b0","repo":"pentaho/pentaho-kettle","slug":"excelwriterstep-exception-maxsheetname","errorCode":"ExcelWriterStep.Exception.MaxSheetName","errorMessage":"ExcelWriterStep.Exception.MaxSheetName (localized message with sheet name)","messagePattern":"ExcelWriterStep\\.Exception\\.MaxSheetName \\(localized message with sheet name\\)","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"plugins/excel/core/src/main/java/org/pentaho/di/trans/steps/excelwriter/ExcelWriterStep.java","lineNumber":655,"sourceCode":"  public static void copyFile( Bowl bowl, FileObject in, FileObject out ) throws KettleException {\n    try ( BufferedInputStream fis = new BufferedInputStream( KettleVFS.getInputStream( in ) );\n        BufferedOutputStream fos = new BufferedOutputStream( KettleVFS.getInstance( bowl )\n          .getOutputStream( out, false ) ) ) {\n      byte[] buf = new byte[1024 * 1024]; // copy in chunks of 1 MB\n      int i = 0;\n      while ( ( i = fis.read( buf ) ) != -1 ) {\n        fos.write( buf, 0, i );\n      }\n    } catch ( Exception e ) {\n      throw new KettleException( e );\n    }\n  }\n\n  public void prepareNextOutputFile() throws KettleException {\n    try {\n      // sheet name shouldn't exceed 31 character\n      if ( data.realSheetname != null && data.realSheetname.length() > 31 ) {\n        throw new KettleException(\n            BaseMessages.getString( PKG, \"ExcelWriterStep.Exception.MaxSheetName\", data.realSheetname ) );\n      }\n      // clear style cache\n      int numOfFields =\n          meta.getOutputFields() != null && meta.getOutputFields().length > 0 ? meta.getOutputFields().length : 0;\n      if ( numOfFields == 0 ) {\n        numOfFields = data.inputRowMeta != null ? data.inputRowMeta.size() : 0;\n      }\n      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      }","sourceCodeStart":637,"sourceCodeEnd":673,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/plugins/excel/core/src/main/java/org/pentaho/di/trans/steps/excelwriter/ExcelWriterStep.java#L637-L673","documentation":"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.","triggerScenarios":"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'.","commonSituations":"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.","solutions":["Shorten the sheet name to 31 characters or fewer","If the sheet name comes from a field, add a substring step to truncate it before this step","Enable/adjust 'Sheet name source' to use a fixed short name","Check for accidental whitespace or suffix appending in the sheetname field mapping"],"exampleFix":"// before\nString sheetName = inputData.getString(\"report_name_long_value\");\n// after\nString sheetName = inputData.getString(\"report_name_long_value\");\nif (sheetName != null && sheetName.length() > 31) { sheetName = sheetName.substring(0, 31); }","handlingStrategy":"validation","validationCode":"String sheetName = environmentSubstitute(meta.getSheetname());\nif (sheetName != null && sheetName.length() > 31) {\n  throw new IllegalArgumentException(\"Sheet name must be <= 31 chars: \" + sheetName);\n}\nif (sheetName != null && sheetName.matches(\".*[\\\\\\\\/?*\\[\\]:].*\")) {\n  throw new IllegalArgumentException(\"Sheet name contains forbidden characters: \" + sheetName);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Truncate field-derived sheet names to 31 chars before the step","Also avoid Excel-forbidden characters and duplicate sheet names","Log the resolved sheet name when it comes from a field"],"tags":["excel","sheet-name","validation","kettle"],"backgroundTag":"value-out-of-range","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"}