apache/beam · error · IllegalArgumentException

Cannot convert value to Row.

Error message

Cannot convert value to Row.

What it means

When a field's FieldType is ROW, convertFromJava accepts only a Map (converted via toRow) or an already-built Row. Any other Java type — String, number, list, POJO — for a row-typed field triggers this IllegalArgumentException because the library has no conversion path from that type to Row.

Solutions

1. Convert the value to a java.util.Map with String keys before writing the row, or wrap it in a Row matching the field's schema
2. Use a MapMapper/avro/json conversion (e.g. via SchemaUtils) to produce a proper Row
3. Change the field type if the value is scalar, or nest correctly if it should be a row

Example fix

// before
rowMap.put("author", "{\"name\":\"Ada\"}"); // throws for ROW field
// after
rowMap.put("author", Map.of("name", "Ada")); // Map is converted via toRow

if (!(v instanceof Map || v instanceof Row)) { throw new IllegalArgumentException("ROW field requires Map or Row, got " + v.getClass()); }

boolean isRowConvertible(Object v) { return v instanceof Map || v instanceof Row; }

try { Row row = FirestoreUtils.toRow(value, schema); } catch (IllegalArgumentException e) { if (e.getMessage().contains("Cannot convert value to Row")) { /* convert to Map/Row upstream or dead-letter */ } else { throw e; } }

When it happens

Trigger: Calling toRow/convertFromJava where a schema field is ROW but the supplied value is neither Map nor Row — e.g. a JSON string, a protobuf message, or a custom object.

Common situations: Producing rows from document data where nested documents were represented as JSON strings or protobuf Value objects; upstream type changes not reflected in the converter input.

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

• Expected Map for map field.
• Cannot convert between types that don't have equivalent…
• Cannot merge two types: +fieldType1.getTypeName()+ and…
• Converting YAML type
• Element argument type

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

Appendix: source

Thrown at sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/firestore/FirestoreUtils.java:307

          throw new IllegalArgumentException("Map value type cannot be null.");
        }
        Map<String, @Nullable Object> rowMap = new HashMap<>();
        for (Map.Entry<?, ?> entry : ((Map<?, ?>) value).entrySet()) {
          rowMap.put(String.valueOf(entry.getKey()), convertFromJava(entry.getValue(), valueType));
        }
        return rowMap;
      case ROW:
        Schema rowSchema = fieldType.getRowSchema();
        if (rowSchema == null) {
          throw new IllegalArgumentException("Row schema cannot be null.");
        }
        if (value instanceof Map) {
          return toRow(castToStringKeyMap((Map<?, ?>) value), rowSchema);
        }
        if (value instanceof Row) {
          return value;
        }
        throw new IllegalArgumentException("Cannot convert value to Row.");
      default:
        throw new IllegalArgumentException("Unsupported field type: " + fieldType);
    }
  }
}

View on GitHub (pinned to 12126d8942)