What causes "Unsupported type '%s'." in apache/beam?

Avoid selecting STRUCT columns; select their scalar fields directly or convert with TO_JSON_STRING in the query.

apache/beam · error · IllegalArgumentException

Unsupported type '%s'.

Error message

Unsupported type '%s'.

What it means

convertSpannerTypeToBeamFieldType throws this when a Spanner type cannot be mapped to a Beam Schema.FieldType. In this SDK version the STRUCT case is explicitly unsupported (nested structs are not convertible), and the default case is only for unrecognized codes. The message carries the raw Spanner type code.

Source

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

        return Schema.FieldType.BOOLEAN;
      case BYTES:
        return Schema.FieldType.BYTES;
      case TIMESTAMP:
      case DATE:
        return Schema.FieldType.DATETIME;
      case INT64:
        return Schema.FieldType.INT64;
      case FLOAT32:
        return Schema.FieldType.FLOAT;
      case FLOAT64:
        return Schema.FieldType.DOUBLE;
      case NUMERIC:
        return Schema.FieldType.DECIMAL;
      case ARRAY:
        return Schema.FieldType.array(
            convertSpannerTypeToBeamFieldType(spannerType.getArrayElementType()));
      case STRUCT:
        throw new IllegalArgumentException(
            String.format("Unsupported type '%s'.", spannerType.getCode()));
      default:
        return Schema.FieldType.STRING;
    }
  }

  public static Struct beamRowToStruct(Row row) {
    Struct.Builder structBuilder = Struct.newBuilder();
    List<Schema.Field> fields = row.getSchema().getFields();
    fields.forEach(
        field -> {
          String column = field.getName();
          switch (field.getType().getTypeName()) {
            case ROW:
              @Nullable Row subRow = row.getRow(column);
              if (subRow == null) {
                structBuilder.set(column).to(beamTypeToSpannerType(field.getType()), null);
              } else {

View on GitHub (pinned to 12126d8942)

Solutions

Avoid selecting STRUCT columns; select their scalar fields directly or convert with TO_JSON_STRING in the query.
Upgrade the Beam SDK to a release with support for the offending Spanner type.
Catch IllegalArgumentException around the read configuration and fail with a clearer application-level message listing allowed types.

Example fix

// before
SELECT id, address_struct FROM users
// after
SELECT id, address_struct.city AS city, address_struct.zip AS zip FROM users

Defensive patterns

Strategy: validation

Validate before calling

if (spannerType.getCode() == Type.Code.STRUCT) {
  throw new IllegalArgumentException("STRUCT columns are not supported; flatten or JSON-encode them");
}

Prevention

Never select STRUCT columns directly; select scalar subfields or TO_JSON_STRING(col).
Keep the Beam GCP SDK up to date for new Spanner type mappings.
Document which column types your pipeline supports.

When it happens

Trigger: Reading Spanner data whose schema contains a STRUCT-typed column (or an unmapped type code) via structTypeToBeamRowSchema, or recursively via an ARRAY<STRUCT> element conversion.

Common situations: Spanner tables with STRUCT columns or generated columns of struct type; ARRAY<STRUCT> results from queries; SDK versions predating nested-struct support.

Related errors

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