What causes "Unsupported spanner type: %s" in apache/beam?

Move JSON/STRUCT data into a STRING column (or flatten STRUCT fields into scalar columns) in the tracked table.

apache/beam · error · IllegalArgumentException

Unsupported spanner type

Error message

Unsupported spanner type: %s

What it means

Thrown by spannerTypeToBeamType when converting a Spanner Type to a Beam Schema.FieldType and the type code is JSON, STRUCT, or otherwise unrecognized. The connector has no Beam representation for these types in change stream schema mapping, so it raises IllegalArgumentException naming the Spanner type.

Solutions

Move JSON/STRUCT data into a STRING column (or flatten STRUCT fields into scalar columns) in the tracked table.
Restrict the change stream / read to tables without JSON or STRUCT columns.
Upgrade the Beam connector in case a newer version added mappings for these type codes.
Post-process upstream: materialize the unsupported column as a supported type via a view before change-stream consumption.

Example fix

// before (Spanner DDL)
CREATE TABLE t (extra JSON);
// after
CREATE TABLE t (extra STRING(MAX)); -- store JSON as string

Defensive patterns

Strategy: validation

Validate before calling

for (Type t : columnTypes) {
  if (t.getCode() == TypeCode.JSON || t.getCode() == TypeCode.STRUCT)
    throw new IllegalArgumentException("Unsupported column type in change stream: " + t.getCode());
}

Try / catch

try { beamType = spannerTypeToBeamType(spannerType); } catch (IllegalArgumentException e) { return Schema.FieldType.STRING.withNullable(true); }

Prevention

Avoid JSON and STRUCT (protobuf) columns in tables consumed via change streams; use STRING instead.
Check table DDL before enabling a change stream on it.
Pin and update the connector version known to support your schema.

When it happens

Trigger: The tracked table contains a JSON or STRUCT (protocol-buffer) typed column, or an array of such a type, so the schema translation recursion reaches an unhandled TypeCode.

Common situations: Tables using Spanner JSON columns or protobuf STRUCT columns included in a change stream; nested ARRAY<JSON>/ARRAY<STRUCT> columns; newer connector versions dropping support the user relied on.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

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

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

View on GitHub (pinned to 12126d8942)