apache/beam · error · IllegalArgumentException

Received an empty Map, but output schema contains required f

Error message

Received an empty Map, but output schema contains required fields: %s

What it means

toBeamRow's map overload converts an empty Map<String,Object> to Row.nullRow only if all schema fields are nullable. When the schema has any non-nullable (required) fields, an empty map cannot satisfy them, so this IllegalArgumentException is thrown listing the required fields.

Source

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

    }

    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",
                requiredFields));
      }
    }
    return rowSchema.getFields().stream()
        .map(
            field ->
                toBeamValue(
                    field, map.get(maybeGetSnakeCase(field.getName(), toCamelCase)), toCamelCase))
        .collect(toRow(rowSchema));
  }

  private static String maybeGetSnakeCase(String str, boolean getSnakeCase) {
    return getSnakeCase ? CaseFormat.LOWER_CAMEL.to(CaseFormat.LOWER_UNDERSCORE, str) : str;
  }

  public static String yamlStringFromMap(@Nullable Map<String, Object> map) {

View on GitHub (pinned to 12126d8942)

Solutions

Populate the map with values for all required fields before conversion.
Make the schema fields nullable if empty objects are legitimate input.
Treat empty maps as missing data and skip/default them before calling toBeamRow.
Fix upstream parsing so empty YAML sections produce a map containing required keys or are dropped.

Example fix

// before
Row row = YamlUtils.toBeamRow(new HashMap<>(), schema, true); // schema has required fields
// after
Map<String, Object> map = new HashMap<>();
map.put("name", "default");
Row row = YamlUtils.toBeamRow(map, schema, true);

Defensive patterns

Strategy: validation

Validate before calling

if (map.isEmpty()) {
  List<String> required = rowSchema.getFields().stream()
      .filter(f -> !f.getType().getNullable())
      .map(Schema.Field::getName)
      .collect(Collectors.toList());
  if (!required.isEmpty()) throw new IllegalArgumentException("Empty map, required: " + required);
}

Type guard

boolean canBeEmptyMap(Schema schema) {
  return schema.getFields().stream().allMatch(f -> f.getType().getNullable());
}

Try / catch

try {
  return YamlUtils.toBeamRow(map, rowSchema, convertNames);
} catch (IllegalArgumentException e) {
  if (e.getMessage() != null && e.getMessage().contains("empty Map")) {
    return Row.nullRow(rowSchema); // only valid if all fields nullable
  }
  throw e;
}

Prevention

Check maps for emptiness before conversion
Drop empty nested YAML sections instead of converting them
Keep required fields minimal; prefer nullable schema fields

When it happens

Trigger: Calling YamlUtils.toBeamRow(new HashMap<>(), rowSchema, ...) (directly, or from toBeamValue when a nested YAML mapping is empty) while rowSchema contains at least one required field.

Common situations: Nested YAML objects present but empty (`metadata:` with no children parsed as empty map), or top-level empty YAML documents loaded as empty maps, against schemas with required fields.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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