apache/beam · error · java.lang.RuntimeException

Failure to register coder

Error message

Failure to register coder

What it means

registerCoderOrThrow registers a Coder with the SdkComponents used to build the pipeline proto. Registration can throw IOException (coder cloud-encoding failures); since translation is not expected to fail on I/O, the checked exception is wrapped in a RuntimeException with this generic message, keeping the original as the cause.

Solutions

1. Check the IOException cause in the stack trace to find which coder failed and why
2. Fix the custom Coder's serialization/verification methods so registration succeeds
3. Replace the problem coder with a standard Beam coder (e.g. AvroCoder, SerializableCoder)

Example fix

// before
class BrokenCoder<T> extends StructuredCoder<T> { /* getEncodedElementByteSize throws */ }
// after
class FixedCoder<T> extends StructuredCoder<T> { @Override protected long getEncodedElementByteSize(T v) { return safeSize(v); } }

try { return ParDoTranslation.registerCoderOrThrow(components, coder); } catch (RuntimeException e) { throw new RuntimeException("Coder registration failed for " + coder, e.getCause()); }

When it happens

Trigger: Calling ParDoTranslation.registerCoderOrThrow (directly or via ParDo translation) with a coder whose registerCoder call throws IOException — e.g. a custom Coder with a broken cloudObject encoding or a coder that fails verification during registration.

Common situations: Custom Coder implementations with faulty registerByteSizeObserver/getEncodedElementByteSize or cloud object serialization; classpath issues preventing reflective coder instantiation inside registration.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• Unexpected IOException:
• ApproximateUnique.PerKey requires its input to use KvCoder
• AvroCoder for GenericRecord requires a schema
• cannot encode a null BitSet
• cannot encode a null byte[]

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

Appendix: source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/util/construction/ParDoTranslation.java:723

      case SET_SPEC:
        return StateSpecs.set(components.getCoder(stateSpec.getSetSpec().getElementCoderId()));

      case ORDERED_LIST_SPEC:
        return StateSpecs.orderedList(
            components.getCoder(stateSpec.getOrderedListSpec().getElementCoderId()));

      case SPEC_NOT_SET:
      default:
        throw new IllegalArgumentException(
            String.format("Unknown %s: %s", RunnerApi.StateSpec.class.getName(), stateSpec));
    }
  }

  public static String registerCoderOrThrow(SdkComponents components, Coder coder) {
    try {
      return components.registerCoder(coder);
    } catch (IOException exc) {
      throw new RuntimeException("Failure to register coder", exc);
    }
  }

  public static RunnerApi.TimerFamilySpec translateTimerFamilySpec(
      TimerSpec timer,
      SdkComponents components,
      Coder<?> keyCoder,
      Coder<BoundedWindow> windowCoder) {
    return RunnerApi.TimerFamilySpec.newBuilder()
        .setTimeDomain(translateTimeDomain(timer.getTimeDomain()))
        .setTimerFamilyCoderId(
            registerCoderOrThrow(components, Timer.Coder.of(keyCoder, windowCoder)))
        .build();
  }

  public static RunnerApi.TimeDomain.Enum translateTimeDomain(TimeDomain timeDomain) {
    switch (timeDomain) {
      case EVENT_TIME:

View on GitHub (pinned to 12126d8942)