{"record":{"id":"2d0bcbb0942cdd81","repo":"apache/beam","slug":"unsupported-spanner-array-type-s-for-column-s","errorCode":null,"errorMessage":"Unsupported spanner array type %s for column %s.","messagePattern":"Unsupported spanner array type (.+?) for column (.+?)\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/spanner/StructUtils.java","lineNumber":485,"sourceCode":"        return struct.getStructList(column).stream()\n            .map(\n                structElem -> {\n                  Schema.@Nullable FieldType fieldType = field.getType().getCollectionElementType();\n                  if (fieldType == null) {\n                    throw new NullPointerException(\n                        \"Null collection element type at field \" + field.getName());\n                  }\n\n                  @Nullable Schema elementSchema = fieldType.getRowSchema();\n                  if (elementSchema == null) {\n                    throw new NullPointerException(\n                        \"Null schema element type at field \" + field.getName());\n                  }\n                  return structToBeamRow(structElem, elementSchema);\n                })\n            .collect(toList());\n      default:\n        throw new RuntimeException(\n            String.format(\"Unsupported spanner array type %s for column %s.\", arrayCode, column));\n    }\n  }\n}\n","sourceCodeStart":467,"sourceCodeEnd":490,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/spanner/StructUtils.java#L467-L490","documentation":"getStructArrayValue's default branch throws this RuntimeException when an ARRAY column's element TypeCode is not among the supported element types. The message includes the array element type code and column name, pointing at exactly which column's array cannot be converted to Beam values.","triggerScenarios":"Reading Spanner ARRAY columns whose element type is unmapped (e.g. newer element types like JSON or PROTO arrays) via structValues during SpannerIO reads.","commonSituations":"Databases using ARRAY<JSON> or proto-backed columns with an older Beam SDK; queries returning arrays of unmapped expression types.","solutions":["Upgrade the Beam Google Cloud Platform SDK to a version mapping the offending array element type.","Rewrite the query to cast the array elements to a supported type (e.g. ARRAY<STRING>).","Catch RuntimeException around the read and log the column/type for a faster support diagnosis."],"exampleFix":"// before\nSELECT ids, tags_json FROM items -- tags_json is ARRAY<JSON>\n// after\nSELECT ids, ARRAY(SELECT CAST(t AS STRING) FROM UNNEST(tags_json) t) AS tags FROM items","handlingStrategy":"try-catch","validationCode":"// pre-check array element codes before reading\nSet<Type.Code> ok = Set.of(Type.Code.BOOL, Type.Code.INT64, Type.Code.FLOAT64,\n    Type.Code.STRING, Type.Code.NUMERIC, Type.Code.TIMESTAMP, Type.Code.DATE, Type.Code.STRUCT);\nboolean supported = ok.contains(arrayType.getArrayElementType().getCode());","typeGuard":null,"tryCatchPattern":"try {\n  Object vals = getStructArrayValue(struct, arrayType, field);\n} catch (RuntimeException e) {\n  LOG.error(\"Cannot convert array column {}: {}\", field.getName(), e.getMessage());\n  throw new IOException(\"Unsupported Spanner array element type; upgrade SDK or cast in query\", e);\n}","preventionTips":["Avoid ARRAY<JSON>/proto arrays until your Beam SDK maps them; cast to ARRAY<STRING> in SQL.","Upgrade the Beam GCP SDK when new Spanner element types are introduced.","Add integration tests covering all array column types in your schema."],"tags":["spanner","arrays","unsupported-type","java"],"backgroundTag":"unsupported-enum-value","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"}