{"record":{"id":"63465aa4fb346a65","repo":"apache/beam","slug":"tuple-like-arrays-are-unsupported-expected-a-single-item","errorCode":null,"errorMessage":"Tuple-like arrays are unsupported. Expected a single item type for field {}","messagePattern":"Tuple-like arrays are unsupported\\. Expected a single item type for field (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/schemas/utils/JsonUtils.java","lineNumber":257,"sourceCode":"      }\n      // Consider non-required properties to be nullable\n      beamSchemaBuilder =\n          addPropertySchemaToBeamSchema(propertyName, propertySchema, beamSchemaBuilder, true);\n    }\n\n    return beamSchemaBuilder.build();\n  }\n\n  private static Schema.Builder addPropertySchemaToBeamSchema(\n      String propertyName,\n      org.everit.json.schema.Schema propertySchema,\n      Schema.Builder beamSchemaBuilder,\n      Boolean isNullable) {\n    java.util.function.BiFunction<String, Schema.FieldType, Schema.Field> fieldConstructor =\n        isNullable ? Schema.Field::nullable : Schema.Field::of;\n    if (propertySchema instanceof org.everit.json.schema.ArraySchema) {\n      if (((ArraySchema) propertySchema).getAllItemSchema() == null) {\n        throw new IllegalArgumentException(\n            \"Tuple-like arrays are unsupported. Expected a single item type for field \"\n                + propertyName);\n      }\n      beamSchemaBuilder =\n          beamSchemaBuilder.addField(\n              fieldConstructor.apply(\n                  propertyName,\n                  Schema.FieldType.array(\n                      beamTypeFromJsonSchemaType(\n                          ((ArraySchema) propertySchema).getAllItemSchema()))));\n    } else {\n      try {\n        beamSchemaBuilder =\n            beamSchemaBuilder.addField(\n                fieldConstructor.apply(propertyName, beamTypeFromJsonSchemaType(propertySchema)));\n      } catch (IllegalArgumentException e) {\n        throw new IllegalArgumentException(\n            \"Unsupported field type \" + propertySchema.getClass() + \" in field \" + propertyName, e);","sourceCodeStart":239,"sourceCodeEnd":275,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/schemas/utils/JsonUtils.java#L239-L275","documentation":"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.","triggerScenarios":"beamSchemaFromJsonSchema on a JSON Schema whose array property lacks a single 'items' schema (tuple form: \"items\":[{...},{...}] or missing items).","commonSituations":"Converting legacy JSON Schemas that use positional tuple arrays; schemas generated from heterogeneous lists; arrays declared without 'items'.","solutions":["Rewrite the array with a single 'items' schema matching one element type","Drop the array or convert it to an object/row schema with named fields if elements differ by position","Validate array properties (single items schema) before passing the JSON Schema to Beam"],"exampleFix":"// before\n{\"tags\":{\"type\":\"array\",\"items\":[{\"type\":\"string\"},{\"type\":\"number\"}]}}\n// after\n{\"tags\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}}}","handlingStrategy":"validation","validationCode":"static void requireSingleItemSchema(org.everit.json.schema.Schema propertySchema, String field) {\n  if (propertySchema instanceof org.everit.json.schema.ArraySchema\n      && ((org.everit.json.schema.ArraySchema) propertySchema).getAllItemSchema() == null) {\n    throw new IllegalArgumentException(\"Field \" + field + \" uses a tuple-like array; Beam requires a single item type\");\n  }\n}","typeGuard":"static boolean hasSingleItemSchema(org.everit.json.schema.Schema s) {\n  return !(s instanceof org.everit.json.schema.ArraySchema)\n      || ((org.everit.json.schema.ArraySchema) s).getAllItemSchema() != null;\n}","tryCatchPattern":"try {\n  Schema s = JsonUtils.beamSchemaFromJsonSchema(jsonSchema);\n} catch (IllegalArgumentException e) {\n  if (e.getMessage().contains(\"Tuple-like arrays\")) {\n    throw new SchemaParseException(\"Fix array field to use a single items schema: \" + e.getMessage(), e);\n  }\n  throw e;\n}","preventionTips":["Replace \"items\":[...] tuple arrays with one uniform items schema before Beam ingestion","Reject arrays without 'items' at schema-ingestion time","Prefer Beam rows (objects) over positional arrays for structured elements"],"tags":["java","json-schema","schemas","arrays"],"backgroundTag":"incompatible-source-type","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T21:17:11.552Z"}