apache/flink · error · InvalidFieldReferenceException

Tuple field expression "{}" out of bounds of {}.

Error message

Tuple field expression "{}" out of bounds of {}.

What it means

Thrown by TupleTypeInfoBase.getFlatFields when the numeric field position parsed from the expression exceeds or equals the tuple arity. For example, referencing 'f3' on a Tuple2 (arity 2, valid indices 0-1). This is an InvalidFieldReferenceException.

Source

Thrown at flink-core/src/main/java/org/apache/flink/api/java/typeutils/TupleTypeInfoBase.java:139

                    keyPosition += cType.getTotalFields() - 1;
                } else {
                    result.add(new FlatFieldDescriptor(offset + keyPosition, type));
                }
                keyPosition++;
            }
        } else {
            String fieldStr = matcher.group(1);
            Matcher fieldMatcher = PATTERN_FIELD.matcher(fieldStr);

            if (!fieldMatcher.matches()) {
                throw new RuntimeException("Invalid matcher pattern");
            }

            field = fieldMatcher.group(2);
            int fieldPos = Integer.valueOf(field);

            if (fieldPos >= this.getArity()) {
                throw new InvalidFieldReferenceException(
                        "Tuple field expression \""
                                + fieldStr
                                + "\" out of bounds of "
                                + this.toString()
                                + ".");
            }
            TypeInformation<?> fieldType = this.getTypeAt(fieldPos);
            String tail = matcher.group(5);
            if (tail == null) {
                if (fieldType instanceof CompositeType) {
                    // forward offsets
                    for (int i = 0; i < fieldPos; i++) {
                        offset += this.getTypeAt(i).getTotalFields();
                    }
                    // add all fields of composite type
                    ((CompositeType<?>) fieldType).getFlatFields("*", offset, result);
                } else {
                    // we found the field to add

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Check the tuple arity and use only valid indices 0 to arity-1.
2. Print TypeInformation.of(MyTuple.class).getArity() to confirm field count.
3. If using config-driven keys, validate the index against arity before calling keyBy.

Example fix

// before
tupleStream.keyBy("f3"); // Tuple2<String, Integer>
// after
tupleStream.keyBy("f1");

int arity = TypeInformation.of(MyTuple.class).getArity();
int pos = Integer.parseInt(fieldExpr.replaceAll("^f", ""));
if (pos < 0 || pos >= arity) {
    throw new IllegalArgumentException(
        "Field position " + pos + " out of range [0, " + (arity - 1) + "]");
}

boolean isValidTupleIndex(TupleTypeInfoBase<?> type, int pos) {
    return pos >= 0 && pos < type.getArity();
}

When it happens

Trigger: Calling tupleType.getFlatFields("f5") on a Tuple3, or keyBy("f2") on a Tuple2. The Integer.parseInt of the field number at line 136 produces a value >= getArity().

Common situations: Developer assumes a tuple has more fields than it does, or the data model changed (Tuple3 -> Tuple2) without updating key references. Common after refactoring tuple schemas or when key indices come from a config file.

Related errors

• Invalid tuple field reference "{}".
• Specifying keys via field positions is only valid for tuple
• Invalid POJO field reference "{}".
• Unable to find field "{}" in type {}.
• Invalid format of POJO field expression "{}".

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