pentaho/pentaho-kettle · error · KettleException

AvroInput.Error.UnionError1

Error message

AvroInput.Error.UnionError1

What it means

Kettle exception thrown by checkUnion when the union schema does not contain exactly two types. The reader only supports nullable unions of the form ['null', X]; a union with 1 or 3+ branches cannot be handled and this error is raised.

Solutions

  1. Normalize the schema so unions are only ['null', <type>] (nullable single-type unions).
  2. Flatten or narrow multi-branch unions upstream (e.g. with an Avro schema-evolution step) before reading.
  3. If a branch genuinely differs per record, split the field into separate columns/paths per branch type.
  4. Check whether a newer Avro plugin/version has broader union support.

Example fix

// before
{"name":"v","type":["null","int","string"]}
// after
{"name":"v","type":["null","string"]}
Defensive patterns

Strategy: validation

Validate before calling

// Reject unions that are not exactly ['null', X]
List<Schema> types = fieldSchema.getTypes();
if (types.size() != 2 || types.stream().noneMatch(t -> t.getType() == Schema.Type.NULL)) {
  throw new IllegalArgumentException("Only nullable 2-branch unions are supported; normalize schema first");
}

Try / catch

try {
  value = reader.convertToKettleValue(record, schema, field);
} catch (KettleException e) {
  if (e.getMessage().contains("UnionError1")) {
    logError("Multi-branch union encountered; normalize to ['null', type] before reading", e);
  }
}

Prevention

When it happens

Trigger: convertToKettleValue encounters a union field and calls checkUnion; s.getTypes().size() != 2 — e.g. unions like ["int","string","null"] or multi-branch unions written by other tools.

Common situations: Avro files produced by systems that emit multi-branch unions (common in schema-evolved or third-party data); Kafka/Confluent Avro records with wide unions; older Pentaho Avro plugin versions with limited union support.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

Thrown at plugins/avro-format/core/src/main/java/org/pentaho/di/trans/steps/avro/input/AvroNestedReader.java:858

  }

  /**
   * Helper function that checks the validity of a union. We can only handle unions that contain two elements: a type
   * and null.
   *
   * @param s the union schema to check
   * @return the type of the element that is not null.
   * @throws KettleException if a problem occurs.
   */
  protected static Schema checkUnion( Schema s ) throws KettleException {
    boolean ok = false;
    List<Schema> types = s.getTypes();

    // the type other than null
    Schema otherSchema = null;

    if ( types.size() != 2 ) {
      throw new KettleException( BaseMessages.getString( PKG, "AvroInput.Error.UnionError1" ) );
    }

    for ( Schema p : types ) {
      if ( p.getType() == Schema.Type.NULL ) {
        ok = true;
      } else {
        otherSchema = p;
      }
    }

    if ( !ok ) {
      throw new KettleException( BaseMessages.getString( PKG, "AvroInput.Error.UnionError2" ) );
    }

    return otherSchema;
  }

  /**

View on GitHub (pinned to f3058517a1)