{"record":{"id":"76568f4fe4ed9b9a","repo":"apache/flink","slug":"error","errorCode":null,"errorMessage":"{}","messagePattern":"\\{\\}","errorType":"exception","errorClass":"NullKeyFieldException","httpStatus":null,"severity":"error","filePath":"flink-core/src/main/java/org/apache/flink/api/java/typeutils/runtime/PojoComparator.java","lineNumber":259,"sourceCode":"        }\n        return true;\n    }\n\n    @Override\n    public int compareToReference(TypeComparator<T> referencedComparator) {\n        PojoComparator<T> other = (PojoComparator<T>) referencedComparator;\n\n        int i = 0;\n        try {\n            for (; i < this.keyFields.length; i++) {\n                int cmp = this.comparators[i].compareToReference(other.comparators[i]);\n                if (cmp != 0) {\n                    return cmp;\n                }\n            }\n            return 0;\n        } catch (NullPointerException npex) {\n            throw new NullKeyFieldException(this.keyFields[i].toString());\n        }\n    }\n\n    @Override\n    public int compare(T first, T second) {\n        int i = 0;\n        for (; i < keyFields.length; i++) {\n            int cmp =\n                    comparators[i].compare(\n                            accessField(keyFields[i], first), accessField(keyFields[i], second));\n            if (cmp != 0) {\n                return cmp;\n            }\n        }\n\n        return 0;\n    }\n","sourceCodeStart":241,"sourceCodeEnd":277,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-core/src/main/java/org/apache/flink/api/java/typeutils/runtime/PojoComparator.java#L241-L277","documentation":"compareToReference in PojoComparator throws NullKeyFieldException (message is just the field name) when comparing against a stored reference raises NullPointerException - i.e. the reference record's key field (or the candidate's) is null during a reference-based comparison used by sort and join algorithms.","triggerScenarios":"Range-partitioning/sort/join paths that call setReference + compareToReference on POJO records where keyFields[i] evaluates to null; the NPE escapes the loop and is converted to NullKeyFieldException carrying the field name only.","commonSituations":"Records with null key fields flowing into sortPartition, co-group, or interval joins; null-producingUDF outputs entering keyed/sorted operators; same root cause as hash() null keys but hit on the reference-comparison path.","solutions":["Normalize null key fields to defaults or sentinel values upstream of sort/join operators","Filter null-keyed records before the operation that triggers comparison","Use the field name in the exception to add the missing null-handling for that specific field"],"exampleFix":"// before\nd.sortPartition(pojo -> pojo.getScore(), Order.ASCENDING); // score may be null\n\n// after\nd.map(p -> p.withScore(p.getScore() == null ? 0L : p.getScore()))\n .sortPartition(pojo -> pojo.getScore(), Order.ASCENDING);","handlingStrategy":"validation","validationCode":"// before sort/join on a POJO field\nboolean hasNullKeys = collection.stream().anyMatch(p -> p.getKeyField() == null);\nif (hasNullKeys) {\n    throw new IllegalArgumentException(\"Null key fields present; normalize before sorting\");\n}","typeGuard":"static boolean isSortSafe(MyPojo p) {\n    return p != null && p.getKeyField() != null;\n}","tryCatchPattern":"try {\n    comparator.compareToReference(ref);\n} catch (NullKeyFieldException e) {\n    // e.getMessage() is the field name whose value is null\n    throw new IllegalArgumentException(\"Null key field: \" + e.getMessage(), e);\n}","preventionTips":["Normalize null key fields to defaults before sortPartition/co-group","Validate key completeness in integration tests with production-like data","Log field name from NullKeyFieldException to speed up triage"],"tags":["pojo","comparator","null-key","sorting"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}