apache/flink · error · UnsupportedOperationException

Workaround hack.

Error message

Workaround hack.

What it means

Thrown by the default implementation of TypeComparator.compareAgainstReference(Comparable[] keys). This method is a stub ('workaround hack') that is not implemented by the base TypeComparator class. Only specific subclasses that need reference-comparison semantics override it; calling it on a comparator that does not override it always fails. It is an internal API not intended for direct user invocation.

Source

Thrown at flink-core/src/main/java/org/apache/flink/api/common/typeutils/TypeComparator.java:317

     */
    public abstract int extractKeys(Object record, Object[] target, int index);

    /**
     * Get the field comparators. This is used together with {@link #extractKeys(Object, Object[],
     * int)} to provide interoperability between different record types. Note, that this should
     * return at least one Comparator and that the number of Comparators must match the number of
     * extracted keys.
     *
     * @return An Array of Comparators for the extracted keys.
     */
    @SuppressWarnings("rawtypes")
    public abstract TypeComparator[] getFlatComparators();

    // --------------------------------------------------------------------------------------------

    @SuppressWarnings("rawtypes")
    public int compareAgainstReference(Comparable[] keys) {
        throw new UnsupportedOperationException("Workaround hack.");
    }
}

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Do not call compareAgainstReference directly; it is an internal method.
2. If writing a custom TypeComparator subclass that needs reference comparison, override compareAgainstReference with a real implementation.
3. Use the standard extractKeys + getFlatComparators path for cross-type key comparison instead.

Example fix

// before — calling the unimplemented stub
int cmp = myComparator.compareAgainstReference(keys); // throws

// after — override in your custom comparator, or use the flat-comparator API
public class MyComparator extends TypeComparator<MyType> {
    @Override
    public int compareAgainstReference(Comparable[] keys) {
        // real implementation
        return keys[0].compareTo(reference);
    }
}

try {
    int cmp = comparator.compareAgainstReference(keys);
} catch (UnsupportedOperationException e) {
    // this comparator does not support reference comparison; use extractKeys + getFlatComparators
}

When it happens

Trigger: Calling compareAgainstReference on a TypeComparator instance whose concrete subclass did not override the method. This happens in internal Flink runtime paths (e.g. certain sort or hash-join probe mechanics) when the comparator type does not support reference-based comparison, or when custom operator code inadvertently calls this internal method.

Common situations: Writing a custom operator that directly uses a TypeComparator and calls compareAgainstReference without checking whether the concrete type supports it. A Flink internal code path that selects the wrong comparator variant for a join or sort. Unlikely to be hit by application-level DataStream/Table API users.

Related errors

• Comparator does not support null-aware serialized comparison
• Record serialization with leading normalized keys not suppor
• Record deserialization with leading normalized keys not supp
• Record serialization with leading normalized keys not suppor
• Record deserialization with leading normalized keys not supp

AI-assisted analysis of apache/flink@2f3c205e92 (2026-08-14). Data as JSON: /api/errors/2ff036eadf5cb70e. Report an issue: GitHub.