apache/beam · error · IncompatibleCoderException

Cannot encode elements of type %s with coder %s: the generic

Error message

Cannot encode elements of type %s with coder %s: the generic supertype %s has %s type parameters, which is less than the number of coder arguments %s has (%s).

What it means

When verifying a parameterized coded type against a coder that itself has coder arguments, the registry resolves the coded class's generic supertype and compares its number of type parameters to the coder's argument count. If the supertype has fewer type parameters than the coder has coder arguments, structural verification is impossible and IncompatibleCoderException is thrown.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/coders/CoderRegistry.java:559

              candidateType, coder, codedClass, candidateType),
          coder,
          candidateType);
    }
    // we have established that this is a covariant upcast... though
    // coders are invariant, we are just checking one direction
    @SuppressWarnings("unchecked")
    TypeDescriptor<T> candidateOkDescriptor = (TypeDescriptor<T>) candidateDescriptor;

    // If the coded type is a parameterized type where any of the actual
    // type parameters are not compatible, then the whole thing is certainly not
    // compatible.
    if ((codedType instanceof ParameterizedType) && !isNullOrEmpty(coder.getCoderArguments())) {
      ParameterizedType parameterizedSupertype =
          (ParameterizedType) candidateOkDescriptor.getSupertype(codedClass).getType();
      Type[] typeArguments = parameterizedSupertype.getActualTypeArguments();
      List<? extends Coder<?>> typeArgumentCoders = coder.getCoderArguments();
      if (typeArguments.length < typeArgumentCoders.size()) {
        throw new IncompatibleCoderException(
            String.format(
                "Cannot encode elements of type %s with coder %s:"
                    + " the generic supertype %s has %s type parameters, which is less than the"
                    + " number of coder arguments %s has (%s).",
                candidateOkDescriptor,
                coder,
                parameterizedSupertype,
                typeArguments.length,
                coder,
                typeArgumentCoders.size()),
            coder,
            candidateOkDescriptor.getType());
      }
      for (int i = 0; i < typeArgumentCoders.size(); i++) {
        try {
          Coder<?> typeArgumentCoder = typeArgumentCoders.get(i);
          verifyCompatible(
              typeArgumentCoder, candidateDescriptor.resolveType(typeArguments[i]).getType());

View on GitHub (pinned to 12126d8942)

Solutions

1. Make getCoderArguments return exactly one coder per type parameter of the encoded type.
2. Update the coder's encoded type declaration to match its coder arguments.
3. If the type genuinely has fewer parameters, drop the extra component coders.

Example fix

// before
public List<Coder<?>> getCoderArguments() { return ImmutableList.of(keyCoder, valueCoder); } // encoded type has 1 param
// after
public List<Coder<?>> getCoderArguments() { return ImmutableList.of(keyCoder); }

if (coder.getCoderArguments().size() > typeArgsOfEncodedClass.length) {
  throw new IllegalStateException("coder has more component coders than type parameters");
}

When it happens

Trigger: verifyCompatible on a ParameterizedType whose coder returns a getCoderArguments list longer than the generic supertype's ActualTypeArguments length — typically a malformed custom coder claiming more component coders than its encoded type has generics.

Common situations: Writing a custom coder for a class with a changed number of type parameters after a refactor or library upgrade; implementing getCoderArguments with a hardcoded list that no longer matches the encoded class's generics.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Cannot infer coder for type parameter
• is not a ParameterizedType
• Cannot provide coder for parameterized type %s: %s
• error when invoking Coder factory method
• cannot register Coder : does not have an accessible method n

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/490c0b6bcb14dda0. Report an issue: GitHub.