pentaho/pentaho-kettle · error · KettleStepException

Error writing line :

Error message

Error writing line :

What it means

XMLOutput.writeField wraps exceptions from writing a single field's XML element (writeCharacters/writeEmptyElement) into a KettleStepException with the generic message 'Error writing line :'. The root cause is in the wrapped exception, usually a StAX writer failure or illegal character data.

Solutions

1. Inspect the cause chain for the real StAX/XMLStreamException message
2. Strip invalid XML characters from field values before the XML Output step
3. Verify output fields are fully configured with valid element names
4. Check the output file/stream is writable and not prematurely closed

Example fix

// before
value = valueMeta.getString( valueData );
// after
value = XmlHandler.addEncodedValue( valueMeta.getString( valueData ) ); // sanitize for XML

for (XMLField f : meta.getOutputFields()) { if (f.getFieldName() == null || f.getFieldName().isEmpty()) throw new IllegalStateException("Empty element name"); }

boolean hasValidElement = fieldName != null && !fieldName.trim().isEmpty();

try { writeField(rowMeta, row, i); } catch (KettleStepException e) { log.error("Field write failed: " + e.getCause(), e); }

When it happens

Trigger: writeRowToFile -> writeField when data.writer.writeCharacters or writeEmptyElement throws, e.g. stream already closed, invalid XML chars in the value, or null element name from a misconfigured field.

Common situations: Illegal control characters in database strings being dumped to XML; output file handle invalidated by OS-level issues; element name empty because output field config is broken.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• Error writing XML row :
• Unable to save to XML file '" + filename + "'
• AddSequenceMeta.Exception.ErrorLoadingStepInfo
• AggregateRowsMeta.Exception.UnableToLoadStepInfo
• AnalyticQueryMeta.Exception.UnableToLoadStepInfoFromXML

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

Appendix: source

Thrown at plugins/xml/core/src/main/java/org/pentaho/di/trans/steps/xmloutput/XMLOutput.java:280

  private Object getNullIfValue( Object valueData, String nullString ) {
    if ( valueData == null && !Utils.isEmpty( nullString ) && isNullIfFieldValueAllowed() ) {
      return nullString;
    }
    return valueData;
  }

  private void writeField( ValueMetaInterface valueMeta, Object valueData, String element ) throws KettleStepException {
    try {
      String value = valueMeta.getString( valueData );
      if ( value != null ) {
        data.writer.writeStartElement( element );
        data.writer.writeCharacters( value );
        data.writer.writeEndElement();
      } else {
        data.writer.writeEmptyElement( element );
      }
    } catch ( Exception e ) {
      throw new KettleStepException( "Error writing line :", e );
    }
  }

  public String buildFilename( boolean ziparchive ) {
    return meta.buildFilename( this, getCopy(), data.splitnr, ziparchive );
  }

  public boolean openNewFile() {
    boolean retval = false;
    data.writer = null;

    try {
      if ( meta.isServletOutput() ) {
        data.writer = XML_OUT_FACTORY.createXMLStreamWriter( getTrans().getServletPrintWriter() );
        if ( meta.getEncoding() != null && meta.getEncoding().length() > 0 ) {
          data.writer.writeStartDocument( meta.getEncoding(), "1.0" );
        } else {
          data.writer.writeStartDocument( Const.XML_ENCODING, "1.0" );

View on GitHub (pinned to f3058517a1)