apache/beam · error · IllegalArgumentException

Tuple-like arrays are unsupported. Expected a single item ty

Error message

Tuple-like arrays are unsupported. Expected a single item type for field {}

What it means

In JsonUtils.addPropertySchemaToBeamSchema, an ArraySchema property must expose a single item schema (getAllItemSchema()); when it is null — i.e. a JSON-Schema tuple-style array or an array with no items — this IllegalArgumentException is thrown for the named field. Beam arrays require one homogeneous element type.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/schemas/utils/JsonUtils.java:257

      }
      // Consider non-required properties to be nullable
      beamSchemaBuilder =
          addPropertySchemaToBeamSchema(propertyName, propertySchema, beamSchemaBuilder, true);
    }

    return beamSchemaBuilder.build();
  }

  private static Schema.Builder addPropertySchemaToBeamSchema(
      String propertyName,
      org.everit.json.schema.Schema propertySchema,
      Schema.Builder beamSchemaBuilder,
      Boolean isNullable) {
    java.util.function.BiFunction<String, Schema.FieldType, Schema.Field> fieldConstructor =
        isNullable ? Schema.Field::nullable : Schema.Field::of;
    if (propertySchema instanceof org.everit.json.schema.ArraySchema) {
      if (((ArraySchema) propertySchema).getAllItemSchema() == null) {
        throw new IllegalArgumentException(
            "Tuple-like arrays are unsupported. Expected a single item type for field "
                + propertyName);
      }
      beamSchemaBuilder =
          beamSchemaBuilder.addField(
              fieldConstructor.apply(
                  propertyName,
                  Schema.FieldType.array(
                      beamTypeFromJsonSchemaType(
                          ((ArraySchema) propertySchema).getAllItemSchema()))));
    } else {
      try {
        beamSchemaBuilder =
            beamSchemaBuilder.addField(
                fieldConstructor.apply(propertyName, beamTypeFromJsonSchemaType(propertySchema)));
      } catch (IllegalArgumentException e) {
        throw new IllegalArgumentException(
            "Unsupported field type " + propertySchema.getClass() + " in field " + propertyName, e);

View on GitHub (pinned to 12126d8942)

Solutions

1. Rewrite the array with a single 'items' schema matching one element type
2. Drop the array or convert it to an object/row schema with named fields if elements differ by position
3. Validate array properties (single items schema) before passing the JSON Schema to Beam

Example fix

// before
{"tags":{"type":"array","items":[{"type":"string"},{"type":"number"}]}}
// after
{"tags":{"type":"array","items":{"type":"string"}}}

static void requireSingleItemSchema(org.everit.json.schema.Schema propertySchema, String field) {
  if (propertySchema instanceof org.everit.json.schema.ArraySchema
      && ((org.everit.json.schema.ArraySchema) propertySchema).getAllItemSchema() == null) {
    throw new IllegalArgumentException("Field " + field + " uses a tuple-like array; Beam requires a single item type");
  }
}

static boolean hasSingleItemSchema(org.everit.json.schema.Schema s) {
  return !(s instanceof org.everit.json.schema.ArraySchema)
      || ((org.everit.json.schema.ArraySchema) s).getAllItemSchema() != null;
}

try {
  Schema s = JsonUtils.beamSchemaFromJsonSchema(jsonSchema);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("Tuple-like arrays")) {
    throw new SchemaParseException("Fix array field to use a single items schema: " + e.getMessage(), e);
  }
  throw e;
}

When it happens

Trigger: beamSchemaFromJsonSchema on a JSON Schema whose array property lacks a single 'items' schema (tuple form: "items":[{...},{...}] or missing items).

Common situations: Converting legacy JSON Schemas that use positional tuple arrays; schemas generated from heterogeneous lists; arrays declared without 'items'.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

• Array schema is not properly formatted or unsupported ({}).
• Unsupported Beam to JSON type: {}
• Unable to parse schema {}
• Unsupported field type {} in field {}
• We currently only support wildcards at terminal parts of sel

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/63465aa4fb346a65. Report an issue: GitHub.