apache/beam · error · CannotProvideCoderException

Cannot provide a coder for type variable

Error message

Cannot provide a coder for type variable %s because the actual type is over specified by multiple incompatible coders %s.

What it means

The type being resolved is a type variable bound in the registry's context to multiple coders, and those coders conflict (over-specified), so no single unambiguous coder can be chosen. getCoderFromTypeDescriptor throws CannotProvideCoderException with ReasonCode.OVER_SPECIFIED. This protects against silently picking one of several incompatible coders for the same type.

Solutions

1. Remove duplicate/conflicting registerCoderForType calls so only one coder exists per type.
2. Register a single explicit coder for the type and retry.
3. Narrow the requested TypeDescriptor to a concrete type with an unambiguous coder.

Example fix

// before
registry.registerCoderForType(TypeDescriptor.of(MyT.class), coderA);
registry.registerCoderForType(TypeDescriptor.of(MyT.class), coderB); // conflict
// after
registry.registerCoderForType(TypeDescriptor.of(MyT.class), coderA); // single binding

if (registry.getCoderTypeRegistrations().stream()
    .filter(r -> r.getType().equals(type)).count() > 1) {
  // conflicting bindings present
}

try {
  coder = registry.getCoder(td);
} catch (CannotProvideCoderException e) {
  // ReasonCode.OVER_SPECIFIED: dedupe registrations or pass explicit coder
}

When it happens

Trigger: getCoder / getDefaultCoders / getCoderFromParameterizedType with a typeCoderBindings multimap where the target type maps to two or more different coders, e.g. the same type variable registered twice with different coders.

Common situations: Registering the same TypeDescriptor twice with different coders; generic method type variables resolving to conflicting context coders during getDefaultCoders for a class hierarchy.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• cannot encode a null Instant
• cannot encode a null Iterable
• cannot encode a null
• cannot encode a null KV
• Cannot encode elements of type

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

Appendix: source

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

   * use the given coders.
   *
   * @throws CannotProvideCoderException if a coder cannot be provided
   */
  private <T> Coder<T> getCoderFromTypeDescriptor(
      TypeDescriptor<T> typeDescriptor, SetMultimap<Type, Coder<?>> typeCoderBindings)
      throws CannotProvideCoderException {
    Type type = typeDescriptor.getType();
    Coder<?> coder;
    if (typeDescriptor.equals(TypeDescriptors.rows())) {
      throw new CannotProvideCoderException(
          "Cannot provide a coder for a Beam Row. Please provide a schema instead using PCollection.setRowSchema.");
    }
    if (typeCoderBindings.containsKey(type)) {
      Set<Coder<?>> coders = typeCoderBindings.get(type);
      if (coders.size() == 1) {
        coder = Iterables.getOnlyElement(coders);
      } else {
        throw new CannotProvideCoderException(
            String.format(
                "Cannot provide a coder for type variable %s"
                    + " because the actual type is over specified by multiple"
                    + " incompatible coders %s.",
                type, coders),
            ReasonCode.OVER_SPECIFIED);
      }
    } else if (type instanceof Class<?>) {
      coder = getCoderFromFactories(typeDescriptor, Collections.emptyList());
    } else if (type instanceof ParameterizedType) {
      coder = getCoderFromParameterizedType((ParameterizedType) type, typeCoderBindings);
    } else if (type instanceof TypeVariable) {
      coder = getCoderFromFactories(typeDescriptor, Collections.emptyList());
    } else if (type instanceof WildcardType) {
      // No coder for an unknown generic type.
      throw new CannotProvideCoderException(
          String.format("Cannot provide a coder for wildcard type %s.", type), ReasonCode.UNKNOWN);
    } else {

View on GitHub (pinned to 12126d8942)