apache/beam · error · CannotProvideCoderException

Class %s has a @DefaultCoder annotation with a null value.

Error message

Class %s has a @DefaultCoder annotation with a null value.

What it means

Thrown by DefaultCoder.coderFor when a @DefaultCoder annotation is present but its value() returns null, i.e. no CoderProvider class was supplied to the annotation. The annotation exists but names no provider, so Beam cannot construct a coder and raises CannotProvideCoderException.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/coders/DefaultCoder.java:109

        Class<?> clazz = typeDescriptor.getRawType();
        DefaultCoder defaultAnnotation = clazz.getAnnotation(DefaultCoder.class);
        if (defaultAnnotation == null) {
          // check if the superclass has DefaultCoder annotation if the class is generated using
          // AutoValue
          if (clazz.getName().contains("AutoValue_")) {
            clazz = clazz.getSuperclass();
            defaultAnnotation = clazz.getAnnotation(DefaultCoder.class);
          }
        }
        if (defaultAnnotation == null) {
          throw new CannotProvideCoderException(
              String.format("Class %s does not have a @DefaultCoder annotation.", clazz.getName()));
        }

        @SuppressWarnings("rawtypes") // this is deliberate, as the user will pass FooCoder.class
        Class<? extends Coder> defaultAnnotationValue = defaultAnnotation.value();
        if (defaultAnnotationValue == null) {
          throw new CannotProvideCoderException(
              String.format(
                  "Class %s has a @DefaultCoder annotation with a null value.", clazz.getName()));
        }

        LOG.debug(
            "DefaultCoder annotation found for {} with value {}", clazz, defaultAnnotationValue);

        Method coderProviderMethod;
        try {
          coderProviderMethod = defaultAnnotationValue.getMethod("getCoderProvider");
        } catch (NoSuchMethodException e) {
          throw new CannotProvideCoderException(
              String.format(
                  "Unable to find 'public static CoderProvider getCoderProvider()' on %s",
                  defaultAnnotationValue),
              e);
        }

View on GitHub (pinned to 12126d8942)

Solutions

Provide the CoderProvider class in the annotation: @DefaultCoder(FooCoder.FooCoderProvider.class).
Check that the annotation used is actually org.apache.beam.sdk.coders.DefaultCoder, not a same-named custom one with a nullable value().
If a custom annotation wrapper is used, ensure it always sets value() to a non-null CoderProvider class.

Example fix

// before
@DefaultCoder
@AutoValue
public abstract class Event { ... }

// after
@DefaultCoder(EventCoder.EventCoderProvider.class)
@AutoValue
public abstract class Event { ... }

Defensive patterns

Strategy: validation

Validate before calling

DefaultCoder ann = MyType.class.getAnnotation(DefaultCoder.class);
if (ann == null || ann.value() == null) {
  throw new IllegalStateException("@DefaultCoder must specify a CoderProvider class");
}

Try / catch

try {
  coder = coderRegistry.getCoder(TypeDescriptor.of(MyType.class));
} catch (CannotProvideCoderException e) {
  coder = MyFallbackCoder.of();
}

Prevention

Never write @DefaultCoder without its value argument.
Verify with a unit test that every pipeline element type resolves a coder.

When it happens

Trigger: Declaring @DefaultCoder on a class without specifying the value, e.g. @DefaultCoder with no CoderProvider class argument (possible with custom annotation misuse or programmatic construction of the annotation proxy).

Common situations: Copy-pasting @DefaultCoder without filling in the coder class; custom annotation implementations where value() is mis-declared with a default of null; annotation processing errors stripping the value.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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