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.

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)

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:
• cannot encode a null Integer
• cannot encode a null Long
• cannot encode a null Short
• cannot encode a null BitSet

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