apache/flink · error · InvalidFieldReferenceException

Invalid POJO field reference "{}".

Error message

Invalid POJO field reference "{}".

What it means

Thrown by PojoTypeInfo.getFlatFields when the fieldExpression string does not match the POJO field-name regex (an identifier starting with a letter, underscore, or '$' — optionally dotted with nested sub-fields — or the '*'/'_' wildcard). The expression is syntactically invalid before any field lookup happens. This is an InvalidFieldReferenceException (extends IllegalArgumentException).

Source

Thrown at flink-core/src/main/java/org/apache/flink/api/java/typeutils/PojoTypeInfo.java:158

    }

    @Override
    @PublicEvolving
    public boolean isSortKeyType() {
        // Support for sorting POJOs that implement Comparable is not implemented yet.
        // Since the order of fields in a POJO type is not well defined, sorting on fields
        //   gives only some undefined order.
        return false;
    }

    @Override
    @PublicEvolving
    public void getFlatFields(
            String fieldExpression, int offset, List<FlatFieldDescriptor> result) {

        Matcher matcher = PATTERN_NESTED_FIELDS_WILDCARD.matcher(fieldExpression);
        if (!matcher.matches()) {
            throw new InvalidFieldReferenceException(
                    "Invalid POJO field reference \"" + fieldExpression + "\".");
        }

        String field = matcher.group(0);
        if (field.equals(ExpressionKeys.SELECT_ALL_CHAR)
                || field.equals(ExpressionKeys.SELECT_ALL_CHAR_SCALA)) {
            // handle select all
            int keyPosition = 0;
            for (PojoField pField : fields) {
                if (pField.getTypeInformation() instanceof CompositeType) {
                    CompositeType<?> cType = (CompositeType<?>) pField.getTypeInformation();
                    cType.getFlatFields(
                            String.valueOf(ExpressionKeys.SELECT_ALL_CHAR),
                            offset + keyPosition,
                            result);
                    keyPosition += cType.getTotalFields() - 1;
                } else {
                    result.add(

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Correct the field expression to a valid Java identifier that exactly matches a POJO field name (letters, digits, '_', '$'; must start with a letter, '_', or '$').
2. For nested access use dot-separated identifiers: "address.city".
3. If you meant all fields, use the wildcard "*" or "_".
4. Inspect the actual POJO type with TypeInformation.of(MyPojo.class) to confirm available field names.

Example fix

// before
dataStream.keyBy("0fieldName");
// after
dataStream.keyBy("fieldName");

private static final Pattern POJO_FIELD =
    Pattern.compile("[\\p{L}_$][\\p{L}\\p{Digit}_$]*(\\..+)?");

void validatePojoFieldExpr(String expr) {
    if (expr == null || !POJO_FIELD.matcher(expr).matches()) {
        throw new IllegalArgumentException("Invalid POJO field expression: " + expr);
    }
}

When it happens

Trigger: Calling dataStream.keyBy("123field"), keyBy(""), keyBy("field-name"), keyBy("a.b.") (trailing dot), or pojoTypeInfo.getFlatFields("a b") on a POJO-typed stream/dataset. Internally reached via ExpressionKeys(String[], TypeInformation) which trims the expression then calls cType.getFlatFields(keyExpr).

Common situations: Developer types a field reference that starts with a digit (valid for Tuple/Row but not POJO), includes hyphens/spaces, has a trailing dot, or passes an empty string. Also occurs when copy-pasting a tuple-style key like 'f0' onto a POJO stream, or when a programmatic field-name source yields a non-identifier value.

Related errors

• Unable to find field "{}" in type {}.
• Invalid format of POJO field expression "{}".
• Invalid tuple field reference "{}".
• This type ({field.getType()}) cannot be used as key.
• This type ({type}) cannot be used as key.

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