apache/beam · error · RuntimeException

Unsupported spanner array type %s for column %s.

Error message

Unsupported spanner array type %s for column %s.

What it means

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.

Source

Thrown at sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/spanner/StructUtils.java:485

        return struct.getStructList(column).stream()
            .map(
                structElem -> {
                  Schema.@Nullable FieldType fieldType = field.getType().getCollectionElementType();
                  if (fieldType == null) {
                    throw new NullPointerException(
                        "Null collection element type at field " + field.getName());
                  }

                  @Nullable Schema elementSchema = fieldType.getRowSchema();
                  if (elementSchema == null) {
                    throw new NullPointerException(
                        "Null schema element type at field " + field.getName());
                  }
                  return structToBeamRow(structElem, elementSchema);
                })
            .collect(toList());
      default:
        throw new RuntimeException(
            String.format("Unsupported spanner array type %s for column %s.", arrayCode, column));
    }
  }
}

View on GitHub (pinned to 12126d8942)

Solutions

1. Upgrade the Beam Google Cloud Platform SDK to a version mapping the offending array element type.
2. Rewrite the query to cast the array elements to a supported type (e.g. ARRAY<STRING>).
3. Catch RuntimeException around the read and log the column/type for a faster support diagnosis.

Example fix

// before
SELECT ids, tags_json FROM items -- tags_json is ARRAY<JSON>
// after
SELECT ids, ARRAY(SELECT CAST(t AS STRING) FROM UNNEST(tags_json) t) AS tags FROM items

// pre-check array element codes before reading
Set<Type.Code> ok = Set.of(Type.Code.BOOL, Type.Code.INT64, Type.Code.FLOAT64,
    Type.Code.STRING, Type.Code.NUMERIC, Type.Code.TIMESTAMP, Type.Code.DATE, Type.Code.STRUCT);
boolean supported = ok.contains(arrayType.getArrayElementType().getCode());

try {
  Object vals = getStructArrayValue(struct, arrayType, field);
} catch (RuntimeException e) {
  LOG.error("Cannot convert array column {}: {}", field.getName(), e.getMessage());
  throw new IOException("Unsupported Spanner array element type; upgrade SDK or cast in query", e);
}

When it happens

Trigger: Reading Spanner ARRAY columns whose element type is unmapped (e.g. newer element types like JSON or PROTO arrays) via structValues during SpannerIO reads.

Common situations: Databases using ARRAY<JSON> or proto-backed columns with an older Beam SDK; queries returning arrays of unmapped expression types.

Related errors

• Unsupported logical type in iterable: %s
• Unsupported iterable type '%s' while translating row to stru
• Unsupported type '%s'.
• Unsupported iterable type '%s' while translating row to stru
• Unsupported spanner type %s for column %s.

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