apache/flink · error · RuntimeException

Cannot instantiate tuple.

Error message

Cannot instantiate tuple.

What it means

TupleSerializer.createInstance() reflectively instantiates the tuple class and creates default instances for every field via the field serializers. Any failure - tuple class not instantiable via the stored constructor, a field serializer's createInstance throwing - is wrapped in RuntimeException('Cannot instantiate tuple.'). It occurs while constructing empty/scratch tuple records for reuse in deserialization or operators.

Source

Thrown at flink-core/src/main/java/org/apache/flink/api/java/typeutils/runtime/TupleSerializer.java:78

        if (stateful) {
            return new TupleSerializer<T>(tupleClass, duplicateFieldSerializers);
        } else {
            return this;
        }
    }

    @Override
    public T createInstance() {
        try {
            T t = instantiateRaw();

            for (int i = 0; i < arity; i++) {
                t.setField(fieldSerializers[i].createInstance(), i);
            }

            return t;
        } catch (Exception e) {
            throw new RuntimeException("Cannot instantiate tuple.", e);
        }
    }

    @Override
    public T createInstance(Object[] fields) {

        try {
            T t = instantiateRaw();

            for (int i = 0; i < arity; i++) {
                t.setField(fields[i], i);
            }

            return t;
        } catch (Exception e) {
            throw new RuntimeException("Cannot instantiate tuple.", e);
        }
    }

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Ensure the tuple class is public, concrete, and has a public no-arg constructor (standard Tuple0..Tuple25 already do).
2. Check the nested cause: if a field serializer's createInstance threw, fix that serializer (return a sensible default instead of throwing).
3. If using a custom tuple subclass, make it static, public, and serializable, or switch to a built-in Tuple/Pojo type.

Example fix

// before
public class MyTuple extends Tuple3<Long,String,Double> { // no no-arg ctor visible
    MyTuple(Long l) { super(l, "", 0D); }
}

// after
public class MyTuple extends Tuple3<Long,String,Double> {
    public MyTuple() {} // public no-arg ctor for reflective instantiation
    public MyTuple(Long l) { super(l, "", 0D); }
}

public static <T extends Tuple> void checkInstantiable(Class<T> tupleClass) {
    int mods = tupleClass.getModifiers();
    if (java.lang.reflect.Modifier.isAbstract(mods) || !java.lang.reflect.Modifier.isPublic(mods)) {
        throw new IllegalStateException(tupleClass + " must be public and concrete");
    }
    try {
        tupleClass.getDeclaredConstructor().newInstance();
    } catch (ReflectiveOperationException e) {
        throw new IllegalStateException(tupleClass + " needs a public no-arg constructor", e);
    }
}

try {
    T t = serializer.createInstance();
} catch (RuntimeException e) {
    // cause is InstantiationException / field serializer failure; fix tuple ctor or field serializer
}

When it happens

Trigger: Creating a default tuple instance when the tupleClass stored in the serializer cannot be instantiated (no public no-arg constructor, abstract class, class not visible to the loader) or when one of the fieldSerializers fails to create a default field value. Often seen after deserializing a TupleSerializer built for a custom tuple subclass.

Common situations: Custom Tuple subclass with no no-arg constructor used as a type. Tuple class not public or loaded by a child classloader that loses visibility on the TaskManager. A custom field TypeSerializer whose createInstance depends on external state and throws.

Related errors

• Tuple needs to be parameterized by using generics.
• Tuple type expected.
• Concrete subclass of Tuple expected.
• Parameterized Tuple type expected.
• Tuple arity '{}' expected but was '{}'.

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