apache/beam · error · IllegalArgumentException

Provided coders for type arguments of %s contain incompatibi

Error message

Provided coders for type arguments of %s contain incompatibilities: Cannot encode elements of type %s with coder %s

What it means

CoderRegistry validated the coders supplied for a class's generic type arguments and found one incompatible: the coder cannot encode a value of the given type. The registry verifies each provided coder against its corresponding type argument via verifyCompatible, and wraps any IncompatibleCoderException into this IllegalArgumentException naming the base class, the offending type, and the coder. This guards against registering a default coder that would fail at encode/decode time.

Source

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

    }
    ParameterizedType parameterizedType = (ParameterizedType) type;
    Type[] typeArgs = parameterizedType.getActualTypeArguments();
    if (knownCoders == null) {
      knownCoders = new Coder<?>[typeArgs.length];
    } else if (typeArgs.length != knownCoders.length) {
      throw new IllegalArgumentException(
          String.format(
              "Class %s has %d parameters, but %d coders are requested.",
              baseClass.getCanonicalName(), typeArgs.length, knownCoders.length));
    }

    SetMultimap<Type, Coder<?>> context = HashMultimap.create();
    for (int i = 0; i < knownCoders.length; i++) {
      if (knownCoders[i] != null) {
        try {
          verifyCompatible(knownCoders[i], typeArgs[i]);
        } catch (IncompatibleCoderException exn) {
          throw new IllegalArgumentException(
              String.format(
                  "Provided coders for type arguments of %s contain incompatibilities:"
                      + " Cannot encode elements of type %s with coder %s",
                  baseClass, typeArgs[i], knownCoders[i]),
              exn);
        }
        context.putAll(getTypeToCoderBindings(typeArgs[i], knownCoders[i]));
      }
    }

    Coder<?>[] result = new Coder<?>[typeArgs.length];
    for (int i = 0; i < knownCoders.length; i++) {
      if (knownCoders[i] != null) {
        result[i] = knownCoders[i];
      } else {
        try {
          result[i] = getCoderFromTypeDescriptor(TypeDescriptor.of(typeArgs[i]), context);
        } catch (CannotProvideCoderException exc) {

View on GitHub (pinned to 12126d8942)

Solutions

1. Check the reported type and coder: ensure the coder's encoded type is assignable from the type argument (Coder.getEncodedTypeDescriptor).
2. Fix the coder binding so each type argument gets a coder for exactly that type.
3. Register coders via registerCoderForType(TypeDescriptor, Coder) with matching generic parameters.
4. If a custom coder's getCoderArguments are wrong, correct them so verifyCompatible recurses correctly.

Example fix

// before
registry.getDefaultCoders(TypeDescriptor.of(MyClass.class), new Coder<?>[]{StringUtf8Coder.of()}); // field is Integer
// after
registry.getDefaultCoders(TypeDescriptor.of(MyClass.class), new Coder<?>[]{VarIntCoder.of()});

for (int i = 0; i < coders.length; i++) {
  if (coders[i] != null && !coders[i].getEncodedTypeDescriptor().getRawType()
      .isAssignableFrom(rawTypeArgs[i])) {
    throw new IllegalStateException("coder " + i + " cannot encode " + rawTypeArgs[i]);
  }
}

static boolean coderMatches(Coder<?> c, Class<?> t) {
  return c != null && c.getEncodedTypeDescriptor().getRawType().isAssignableFrom(t);
}

try {
  Coder<T> coder = registry.getCoder(typeDescriptor, contextCoders);
} catch (IllegalArgumentException e) {
  // log coder/type pair, fall back to registry-inferred coder
}

When it happens

Trigger: Calling CoderRegistry.getDefaultCoders (directly or via getCoder) for a parameterized type while passing a context array of known coders where coder[i] does not handle typeArgs[i], e.g. a Coder<Integer> bound to a String type argument.

Common situations: Generic pipeline code with TypeDescriptor-supplied coders; refactoring a field's Java type without updating the registered coder; registering a custom coder for a superclass while the actual element type is a different branch of the hierarchy.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Unable to provide coder for %s, this factory can only provid
• error when invoking Coder factory method
• cannot register Coder : does not have an accessible method n
• cannot register Coder : method named 'of' with arguments of
• cannot register Coder : method named 'of' with arguments of

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