{"record":{"id":"15859602c04942f3","repo":"apache/beam","slug":"expected-map-for-map-field","errorCode":null,"errorMessage":"Expected Map for map field.","messagePattern":"Expected Map for map field\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/firestore/FirestoreUtils.java","lineNumber":285,"sourceCode":"        }\n        return value.toString().getBytes(java.nio.charset.StandardCharsets.UTF_8);\n      case ARRAY:\n      case ITERABLE:\n        if (!(value instanceof Iterable)) {\n          throw new IllegalArgumentException(\"Expected Iterable for array field.\");\n        }\n        FieldType elementType = fieldType.getCollectionElementType();\n        if (elementType == null) {\n          throw new IllegalArgumentException(\"Collection element type cannot be null.\");\n        }\n        List<@Nullable Object> rowList = new ArrayList<>();\n        for (Object item : (Iterable<?>) value) {\n          rowList.add(convertFromJava(item, elementType));\n        }\n        return rowList;\n      case MAP:\n        if (!(value instanceof Map)) {\n          throw new IllegalArgumentException(\"Expected Map for map field.\");\n        }\n        FieldType valueType = fieldType.getMapValueType();\n        if (valueType == null) {\n          throw new IllegalArgumentException(\"Map value type cannot be null.\");\n        }\n        Map<String, @Nullable Object> rowMap = new HashMap<>();\n        for (Map.Entry<?, ?> entry : ((Map<?, ?>) value).entrySet()) {\n          rowMap.put(String.valueOf(entry.getKey()), convertFromJava(entry.getValue(), valueType));\n        }\n        return rowMap;\n      case ROW:\n        Schema rowSchema = fieldType.getRowSchema();\n        if (rowSchema == null) {\n          throw new IllegalArgumentException(\"Row schema cannot be null.\");\n        }\n        if (value instanceof Map) {\n          return toRow(castToStringKeyMap((Map<?, ?>) value), rowSchema);\n        }","sourceCodeStart":267,"sourceCodeEnd":303,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/firestore/FirestoreUtils.java#L267-L303","documentation":"FirestoreV1's schema-conversion helper convertFromJava validates that a value destined for a MAP-typed field in the Beam Row schema is actually a java.util.Map. When a different Java type (list, POJO, string) is supplied for a map field, the conversion cannot proceed and this IllegalArgumentException is thrown. It is a type-contract check between the user's Java value and the declared schema field type.","triggerScenarios":"Calling FirestoreUtils.toRow / convertFromJava with a PCollection element whose schema declares a field as MAP (e.g. map<string, string>) but whose Java value is not a Map instance — e.g. a List of pairs, a String, or a custom POJO holding map-like data.","commonSituations":"Users build a Write's schema with a map field but populate it from Firestore document data or a Proto struct converted to the wrong Java type; schema inference mismatched with the actual element class; refactors changed the field type but not the producer code.","solutions":["Make the value supplied for the map field a java.util.Map<String, Object> matching the schema's key/value types","Check the field's FieldType in the Schema and align the producer code with it","If the source value is a list of key-value pairs, transform it into a Map before calling toRow","If the field was never intended to be a map, change the Schema FieldType to match the actual value type"],"exampleFix":"// before\nSchema schema = Schema.of(Field.of(\"labels\", FieldType.map(FieldType.STRING, FieldType.STRING)));\nRow row = toRow(Map.of(\"labels\", List.of(\"a=1\")), schema); // throws\n// after\nRow row = toRow(Map.of(\"labels\", Map.of(\"a\", \"1\")), schema);","handlingStrategy":"type-guard","validationCode":"if (!(value instanceof Map)) { throw new IllegalArgumentException(\"field 'labels' must be a Map\"); }","typeGuard":"boolean isStringKeyMap(Object v) { return v instanceof Map && ((Map<?,?>) v).keySet().stream().allMatch(k -> k instanceof String); }","tryCatchPattern":"try { Row row = FirestoreUtils.toRow(mapValue, schema); } catch (IllegalArgumentException e) { if (e.getMessage().contains(\"Expected Map\")) { /* log field type mismatch, route to dead-letter */ } else { throw e; } }","preventionTips":["Keep schema field types and producer classes generated from one source (e.g. Schema creation from POJO annotations)","Unit-test toRow conversions against representative documents","Validate PCollection schemas early in the pipeline"],"tags":["java","firestore","schema","type-mismatch"],"backgroundTag":"type-mismatch","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}