pentaho/pentaho-kettle · error · KettleXMLException

Unable to load step info from XML

Error message

Unable to load step info from XML

What it means

ExcelOutputMeta.loadXML parses the step's custom XML node (fonts, colors, etc.) and wraps any parsing failure in this KettleXMLException. It means the <step> XML for an Excel Output step could not be read — typically a malformed or unexpected XML structure in the .ktr file.

Solutions

  1. Inspect the wrapped cause to find which tag or value failed to parse.
  2. Open the .ktr in Spoon and re-save the Excel Output step to regenerate canonical XML.
  3. Compare the step's XML against a freshly created Excel Output step and fix mismatched/missing tags.
  4. Confirm the PDI version that wrote the .ktr matches the runtime version; migrate via Spoon rather than manual edits.
  5. Check that font/color code values in the XML are valid integers recognized by getFontColorByCode.

Example fix

// before: hand-edited tag with invalid value
<row_font_color>dark</row_font_color>
// after: valid numeric color code
<row_font_color>0</row_font_color>
Defensive patterns

Strategy: try-catch

Validate before calling

Document doc = XMLHandler.loadXMLFile( new File( ktrPath ) );
// validate Excel Output custom tags exist before loading
Node stepNode = XMLHandler.getSubNode( doc, "step" );
if ( stepNode == null ) throw new IllegalStateException( "Malformed Excel Output XML" );

Try / catch

try { transMeta.loadXML( file, ... ); } catch ( KettleXMLException e ) { logError( "Excel Output XML invalid: " + e.getCause(), e ); }

Prevention

When it happens

Trigger: The constructor/loadXML path hits an exception while calling XMLHandler.getTagValue on the custom node (e.g. node is null, wrong element names, invalid numeric color/font codes passed to getFontColorByCode).

Common situations: Hand-edited .ktr files; .ktr produced by a newer/older PDI version with a different XML schema; corrupted copy/paste of step XML between transformations; missing 'custom' node attributes.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at plugins/excel/core/src/main/java/org/pentaho/di/trans/steps/exceloutput/ExcelOutputMeta.java:899

      header_background_color =
        getFontColorByCode( Const.NVL( XMLHandler.getTagValue( customnode, "header_background_color" ), ""
          + FONT_COLOR_NONE ) );
      header_row_height = XMLHandler.getTagValue( customnode, "header_row_height" );
      header_alignment =
        getFontAlignmentByCode( Const.NVL( XMLHandler.getTagValue( customnode, "header_alignment" ), "" ) );
      header_image = XMLHandler.getTagValue( customnode, "header_image" );
      // Row font
      row_font_name = getFontNameByCode( Const.NVL( XMLHandler.getTagValue( customnode, "row_font_name" ), "" ) );
      row_font_size = Const.NVL( XMLHandler.getTagValue( customnode, "row_font_size" ), "" + DEFAULT_FONT_SIZE );
      row_font_color =
        getFontColorByCode( Const.NVL( XMLHandler.getTagValue( customnode, "row_font_color" ), ""
          + FONT_COLOR_BLACK ) );
      row_background_color =
        getFontColorByCode( Const.NVL( XMLHandler.getTagValue( customnode, "row_background_color" ), ""
          + FONT_COLOR_NONE ) );

    } catch ( Exception e ) {
      throw new KettleXMLException( "Unable to load step info from XML", e );
    }
  }

  public String getNewLine( String fformat ) {
    String nl = System.getProperty( "line.separator" );

    if ( fformat != null ) {
      if ( fformat.equalsIgnoreCase( "DOS" ) ) {
        nl = "\r\n";
      } else if ( fformat.equalsIgnoreCase( "UNIX" ) ) {
        nl = "\n";
      }
    }

    return nl;
  }

  @Override

View on GitHub (pinned to f3058517a1)