{"record":{"id":"4e8c8605ff8d8726","repo":"apache/flink","slug":"unknown-field-name-s-for-mapping-to-a-row-posit","errorCode":null,"errorMessage":"Unknown field name '%s' for mapping to a row position. Available names are: %s","messagePattern":"Unknown field name '(.+?)' for mapping to a row position\\. Available names are: (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"flink-core/src/main/java/org/apache/flink/api/java/typeutils/runtime/RowSerializer.java","lineNumber":432,"sourceCode":"        RowSerializer that = (RowSerializer) o;\n        return supportsRowKind == that.supportsRowKind\n                && Arrays.equals(fieldSerializers, that.fieldSerializers);\n    }\n\n    @Override\n    public int hashCode() {\n        int result = Objects.hash(supportsRowKind);\n        result = 31 * result + Arrays.hashCode(fieldSerializers);\n        return result;\n    }\n\n    // --------------------------------------------------------------------------------------------\n\n    private int getPositionByName(String fieldName) {\n        assert positionByName != null;\n        final Integer targetPos = positionByName.get(fieldName);\n        if (targetPos == null) {\n            throw new RuntimeException(\n                    String.format(\n                            \"Unknown field name '%s' for mapping to a row position. \"\n                                    + \"Available names are: %s\",\n                            fieldName, positionByName.keySet()));\n        }\n        return targetPos;\n    }\n\n    private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException {\n        in.defaultReadObject();\n        this.mask = new boolean[rowKindOffset + fieldSerializers.length];\n        this.reuseRowPositionBased = new Row(fieldSerializers.length);\n    }\n\n    // --------------------------------------------------------------------------------------------\n    // Serialization utilities\n    // --------------------------------------------------------------------------------------------\n","sourceCodeStart":414,"sourceCodeEnd":450,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-core/src/main/java/org/apache/flink/api/java/typeutils/runtime/RowSerializer.java#L414-L450","documentation":"RowSerializer.getPositionByName() looks up a field name in the positionByName map to find its serializer position. If the field name is not present in the map, this RuntimeException is thrown with a String.format message listing the unknown name and all available names. The serializer's schema and the Row's field names must agree exactly — any field name in the Row that is not in the serializer's name→position map triggers this.","triggerScenarios":"During name-based copy, serialize, or deserialize, the code calls getPositionByName(fieldName) for each field in a name-based Row. If the Row contains a field name that was not provided when the serializer's positionByName map was constructed, the lookup returns null and this exception fires.","commonSituations":"The Row was created with field names that differ from the serializer's schema (typo, renamed column, different casing); a schema evolution added a new named field to the Row but the serializer was not updated with the new name; two sources with overlapping-but-different field names are unioned; the field-name set in the RowTypeInfo does not match the names used by the upstream operator that created the Row.","solutions":["Ensure the field names in the Row exactly match the keys of the serializer's positionByName map (including case).","Update the RowTypeInfo / RowSerializer field-name map whenever a column is renamed or added.","If the Row may carry extra fields not in the serializer schema, project it to only the known fields before serialization.","Use a shared schema definition (e.g., a Schema or TableSchema) to build both the Row and the serializer consistently."],"exampleFix":"// before — Row field name 'userName' not in serializer schema\nLinkedHashMap<String, Integer> names = new LinkedHashMap<>();\nnames.put(\"id\", 0); names.put(\"name\", 1);\nRowSerializer ser = new RowSerializer(new TypeSerializer[]{intSer, strSer}, names);\nRow row = Row.withNames().setField(\"id\", 1).setField(\"userName\", \"a\");\nser.serialize(row, output); // 'userName' not in {id, name} → exception\n\n// after — Row field names match serializer schema\nRow row = Row.withNames().setField(\"id\", 1).setField(\"name\", \"a\");\nser.serialize(row, output); // OK","handlingStrategy":"validation","validationCode":"// Validate that all field names in the Row are known to the serializer schema\npublic static void validateFieldNames(Row row, Set<String> schemaNames) {\n    Set<String> rowNames = row.getFieldNames(false);\n    if (rowNames == null) return; // position-based, skip\n    for (String name : rowNames) {\n        if (!schemaNames.contains(name)) {\n            throw new IllegalArgumentException(\n                \"Unknown field name '\" + name + \"'; known names: \" + schemaNames);\n        }\n    }\n}","typeGuard":"public static boolean allNamesInSchema(Row row, Set<String> schemaNames) {\n    Set<String> rowNames = row.getFieldNames(false);\n    if (rowNames == null) return true;\n    return schemaNames.containsAll(rowNames);\n}","tryCatchPattern":"try {\n    serializer.serialize(namedRecord, output);\n} catch (RuntimeException e) {\n    if (e.getMessage().contains(\"Unknown field name\")) {\n        log.error(\"Row has field names not in serializer schema: {}\",\n            e.getMessage());\n        // fix the Row or update the serializer schema\n    }\n    throw e;\n}","preventionTips":["Keep Row field names and serializer field-name map in sync — share a single schema constant.","Validate field names at the source before they reach the serializer.","After renaming a column, update the RowTypeInfo and all producers.","Use case-sensitive, consistent field naming across the pipeline."],"tags":["row","serializer","named-fields","schema-mismatch","field-name"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}