apache/beam · error · UnsupportedOperationException

Converting YAML type

Error message

Converting YAML type '%s' to '%s' is not supported

What it means

toBeamValue only knows how to convert a limited set of YAML value types (scalars, lists, maps-to-row) to schema field types; anything else, or a type/field-type pairing with no conversion path, hits the final UnsupportedOperationException with the Java value class and target FieldType in the message.

Solutions

1. Align the YAML value type with the schema field type (e.g. provide a mapping where the schema expects a row).
2. Change the schema field type to match what the YAML actually contains.
3. Pre-convert unsupported YAML types (e.g. timestamps to strings, binary to base64 strings) before calling toBeamRow.
4. Upgrade Beam — YamlUtils gains more conversions over time.
5. Do a manual pre-pass: parse with SnakeYAML yourself and construct the Row field-by-field for exotic types.

Example fix

// before (YAML)
created: 2023-01-01T00:00:00Z // parsed as Date, unsupported target
// after
created: "2023-01-01T00:00:00Z" // string, or declare field as DATETIME supported in newer Beam

Object v = yamlMap.get(fieldName);
Schema.TypeName t = schema.getField(fieldName).getType().getTypeName();
if (v instanceof String && !(t == Schema.TypeName.STRING || t.isNumericType()))
  throw new IllegalArgumentException("Unsupported YAML scalar for " + t);
if (v instanceof Map && !(t == Schema.TypeName.ROW || t == Schema.TypeName.MAP))
  throw new IllegalArgumentException("Mapping not allowed for " + t);
if (v instanceof List && !(t == Schema.TypeName.ARRAY || t == Schema.TypeName.ITERABLE))
  throw new IllegalArgumentException("Sequence not allowed for " + t);

boolean yamlValueMatches(Object v, Schema.FieldType t) {
  if (v == null) return t.getNullable();
  switch (t.getTypeName()) {
    case STRING: return v instanceof String || v instanceof Number || v instanceof Boolean;
    case ROW: case MAP: return v instanceof Map;
    case ARRAY: case ITERABLE: return v instanceof List;
    default: return v instanceof String || v instanceof Number || v instanceof Boolean;
  }
}

try {
  return YamlUtils.toBeamRow(yamlString, schema);
} catch (UnsupportedOperationException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Converting YAML type")) {
    logger.warning("Unsupported YAML conversion: " + e.getMessage());
    return null; // or dead-letter the record
  }
  throw e;
}

When it happens

Trigger: A YAML value's Java runtime type has no conversion for the target FieldType — e.g. a MAP field returns the raw yamlValue unchecked but scalar-to-LOGICAL/BYTES/DATETIME combinations, or a List where the field is not an array/iterable, reach the fall-through throw after the instanceof checks.

Common situations: YAML documents with dates/timestamps parsed into Date objects for DATETIME fields in older versions, binary data for BYTES fields, or mismatched schema (field declared INTEGER but YAML has a nested mapping).

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

• Cannot convert between types that don't have equivalent…
• Cannot convert value to Row.
• Cannot merge two types: +fieldType1.getTypeName()+ and…
• Element argument type
• Expected a schema with a single array field but received

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

Appendix: source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/schemas/utils/YamlUtils.java:148

                          toBeamValue(field.withType(innerType), v, convertNamesToCamelCase)))
              .collect(Collectors.toList());
    }

    if (yamlValue instanceof Map) {
      if (fieldType.getTypeName() == Schema.TypeName.ROW) {
        Schema nestedSchema =
            Preconditions.checkNotNull(
                fieldType.getRowSchema(),
                "Received a YAML '%s' type, but output schema field '%s' does not define a Row Schema",
                yamlValue.getClass(),
                fieldType);
        return toBeamRow((Map<String, Object>) yamlValue, nestedSchema, convertNamesToCamelCase);
      } else if (fieldType.getTypeName() == Schema.TypeName.MAP) {
        return yamlValue;
      }
    }

    throw new UnsupportedOperationException(
        String.format(
            "Converting YAML type '%s' to '%s' is not supported", yamlValue.getClass(), fieldType));
  }

  @SuppressWarnings("nullness")
  public static Row toBeamRow(
      @Nullable Map<String, Object> map, Schema rowSchema, boolean toCamelCase) {
    if (map == null || map.isEmpty()) {
      List<Field> requiredFields =
          rowSchema.getFields().stream()
              .filter(field -> !field.getType().getNullable())
              .collect(Collectors.toList());
      if (requiredFields.isEmpty()) {
        return Row.nullRow(rowSchema);
      } else {
        throw new IllegalArgumentException(
            String.format(
                "Received an empty Map, but output schema contains required fields: %s",

View on GitHub (pinned to 12126d8942)