{"record":{"id":"e13526f00bfe21d3","repo":"apache/flink","slug":"record-serialization-with-leading-normalized-keys","errorCode":null,"errorMessage":"Record serialization with leading normalized keys not supported.","messagePattern":"Record serialization with leading normalized keys not supported\\.","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"flink-core/src/main/java/org/apache/flink/api/java/typeutils/runtime/NullAwareComparator.java","lineNumber":193,"sourceCode":"            if (record == null) {\n                target.putBoolean(offset, false);\n                // write padding\n                for (int j = 0; j < numBytes - 1; j++) {\n                    target.put(offset + 1 + j, (byte) 0);\n                }\n            }\n            // write a non-null byte with key\n            else {\n                target.putBoolean(offset, true);\n                // write key\n                wrappedComparator.putNormalizedKey(record, target, offset + 1, numBytes - 1);\n            }\n        }\n    }\n\n    @Override\n    public void writeWithKeyNormalization(T record, DataOutputView target) throws IOException {\n        throw new UnsupportedOperationException(\n                \"Record serialization with leading normalized keys not supported.\");\n    }\n\n    @Override\n    public T readWithKeyDenormalization(T reuse, DataInputView source) throws IOException {\n        throw new UnsupportedOperationException(\n                \"Record deserialization with leading normalized keys not supported.\");\n    }\n\n    @Override\n    public boolean invertNormalizedKey() {\n        return wrappedComparator.invertNormalizedKey();\n    }\n\n    @Override\n    public TypeComparator<T> duplicate() {\n        return new NullAwareComparator<T>(wrappedComparator.duplicate(), order);\n    }","sourceCodeStart":175,"sourceCodeEnd":211,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-core/src/main/java/org/apache/flink/api/java/typeutils/runtime/NullAwareComparator.java#L175-L211","documentation":"NullAwareComparator.writeWithKeyNormalization() always throws UnsupportedOperationException. Normalized-key serialization would need to write the null-flag byte at a position the wrapped comparator's key-normalization protocol cannot express (the wrapper prepends its own null byte in putNormalizedKey), so this TypeComparator feature is intentionally unimplemented.","triggerScenarios":"A sort/min-max algorithm or runtime path that requires 'serialization with key normalization' (normalizing keys that are not fixed-length normalized keys) calls this method on a null-aware field comparator; the feature check supportsSerializationWithKeyNormalization() returns false, so callers should have probed it first.","commonSituations":"Custom operators implementing large-scale sort with key-normalized serialization; runtime paths configured with comparators whose supportsNormalizedKey() is false falling back to key-normalized serialization on a null-aware field.","solutions":["Check comparator.supportsSerializationWithKeyNormalization() before using key-normalization serialization paths","Route sorting through the composite comparator (RowComparator), which implements these methods at composite level","Make the wrapped field non-null in the schema (disable nullability) so the plain comparator is used"],"exampleFix":"// before\ncomparator.writeWithKeyNormalization(record, target);\n\n// after\nif (comparator.supportsSerializationWithKeyNormalization()) {\n    comparator.writeWithKeyNormalization(record, target);\n} else {\n    serializer.serialize(record, target);\n}","handlingStrategy":"validation","validationCode":"if (!comparator.supportsSerializationWithKeyNormalization()) {\n    serializer.serialize(record, target); // plain path\n} else {\n    comparator.writeWithKeyNormalization(record, target);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always probe supportsSerializationWithKeyNormalization() before key-normalized writes","Keep nullability handling at the composite type level","Test nullable-field sorting paths in custom operator development"],"tags":["comparator","null-handling","normalized-key","unsupported-operation"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}