{"record":{"id":"03b973e9d72291f0","repo":"pentaho/pentaho-kettle","slug":"avroinput-error-unionerror1","errorCode":null,"errorMessage":"AvroInput.Error.UnionError1","messagePattern":"AvroInput\\.Error\\.UnionError1","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"plugins/avro-format/core/src/main/java/org/pentaho/di/trans/steps/avro/input/AvroNestedReader.java","lineNumber":858,"sourceCode":"  }\n\n  /**\n   * Helper function that checks the validity of a union. We can only handle unions that contain two elements: a type\n   * and null.\n   *\n   * @param s the union schema to check\n   * @return the type of the element that is not null.\n   * @throws KettleException if a problem occurs.\n   */\n  protected static Schema checkUnion( Schema s ) throws KettleException {\n    boolean ok = false;\n    List<Schema> types = s.getTypes();\n\n    // the type other than null\n    Schema otherSchema = null;\n\n    if ( types.size() != 2 ) {\n      throw new KettleException( BaseMessages.getString( PKG, \"AvroInput.Error.UnionError1\" ) );\n    }\n\n    for ( Schema p : types ) {\n      if ( p.getType() == Schema.Type.NULL ) {\n        ok = true;\n      } else {\n        otherSchema = p;\n      }\n    }\n\n    if ( !ok ) {\n      throw new KettleException( BaseMessages.getString( PKG, \"AvroInput.Error.UnionError2\" ) );\n    }\n\n    return otherSchema;\n  }\n\n  /**","sourceCodeStart":840,"sourceCodeEnd":876,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/plugins/avro-format/core/src/main/java/org/pentaho/di/trans/steps/avro/input/AvroNestedReader.java#L840-L876","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Normalize the schema so unions are only ['null', <type>] (nullable single-type unions).","Flatten or narrow multi-branch unions upstream (e.g. with an Avro schema-evolution step) before reading.","If a branch genuinely differs per record, split the field into separate columns/paths per branch type.","Check whether a newer Avro plugin/version has broader union support."],"exampleFix":"// before\n{\"name\":\"v\",\"type\":[\"null\",\"int\",\"string\"]}\n// after\n{\"name\":\"v\",\"type\":[\"null\",\"string\"]}","handlingStrategy":"validation","validationCode":"// Reject unions that are not exactly ['null', X]\nList<Schema> types = fieldSchema.getTypes();\nif (types.size() != 2 || types.stream().noneMatch(t -> t.getType() == Schema.Type.NULL)) {\n  throw new IllegalArgumentException(\"Only nullable 2-branch unions are supported; normalize schema first\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  value = reader.convertToKettleValue(record, schema, field);\n} catch (KettleException e) {\n  if (e.getMessage().contains(\"UnionError1\")) {\n    logError(\"Multi-branch union encountered; normalize to ['null', type] before reading\", e);\n  }\n}","preventionTips":["Enforce nullable-single-type unions in producer schema conventions","Add an upstream schema-normalization step for third-party Avro data","Audit schemas with a linter that flags unions with more than 2 branches"],"tags":["avro","union-type","unsupported-shape"],"backgroundTag":"unsupported-operation","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"}