apache/beam · error · IllegalArgumentException

Unsupported field type: %s

Error message

Unsupported field type: %s

What it means

MutationUtils.setBeamValueToKey() also validates the field's TypeName in its switch; any TypeName not among the key-supported cases reaches the default branch and throws IllegalArgumentException('Unsupported field type: %s'). This is the same guard as the logical-type check but at the Beam FieldType level.

Source

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

              Timestamp.ofTimeMicroseconds(dateTime.toInstant().getMillis() * 1_000L));
        }
        break;
      case BOOLEAN:
        keyBuilder.append(row.getBoolean(columnName));
        break;
      case STRING:
        keyBuilder.append(row.getString(columnName));
        break;
      case BYTES:
        byte @Nullable [] bytes = row.getBytes(columnName);
        if (bytes == null) {
          keyBuilder.append((ByteArray) null);
        } else {
          keyBuilder.append(ByteArray.copyFrom(bytes));
        }
        break;
      default:
        throw new IllegalArgumentException(
            String.format("Unsupported field type: %s", field.getTypeName()));
    }
  }

  private static void setBeamValueToMutation(
      Mutation.WriteBuilder mutationBuilder,
      Schema.FieldType fieldType,
      String columnName,
      Row row) {
    switch (fieldType.getTypeName()) {
      case BYTE:
        @Nullable Byte byteValue = row.getByte(columnName);
        if (byteValue == null) {
          mutationBuilder.set(columnName).to(((Long) null));
        } else {
          mutationBuilder.set(columnName).to(byteValue);
        }
        break;

View on GitHub (pinned to 12126d8942)

Solutions

1. Restrict key fields to scalar Beam FieldTypes (STRING, INT64, FLOAT64, BOOLEAN, DATETIME, BYTES).
2. Extract scalar components from nested rows and use those as the key.
3. Check the reported TypeName in the message and adjust the Beam schema accordingly.

Example fix

// before
FieldType keyType = FieldType.row(nestedSchema) // ROW not supported
// after
FieldType keyType = FieldType.STRING

TypeName tn = field.getType().getTypeName();
if (tn.isCompositeType() || tn.isCollectionType()) throw new IllegalArgumentException("non-scalar key field: " + field.getName());

boolean isScalarTypeName(TypeName tn) { return !tn.isCompositeType() && !tn.isCollectionType() && !tn.isMapType(); }

try { keyBuilder = setBeamValueToKey(keyBuilder, field, row); } catch (IllegalArgumentException e) { /* use scalar component instead */ }

When it happens

Trigger: A Beam Row key field has a TypeName not supported for Spanner keys (e.g. ROW, ARRAY, MAP, ITERABLE) when createKeyFromBeamRow builds the key.

Common situations: Nested Beam schemas used as key fields; mapping a composite/struct source key straight to the Spanner primary key; schema inference producing ROW-typed fields.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Unsupported logical type in key: %s
• Unsupported logical type: %s
• Cannot provide a coder for a Beam Row. Please provide a sche
• Failed to decode Schema due to an error decoding Field proto
• Encountered UNSPECIFIED AtomicType

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