apache/beam · error · RuntimeException

Error serializing via Coder

Error message

Error serializing via Coder

What it means

SerializableViaCoder serializes a value by encoding it with its Coder into a byte array so it can cross serialization boundaries (e.g. Hamcrest matcher distribution to workers). If CoderUtils.encodeToByteArray throws CoderException, it is wrapped in a RuntimeException with this message.

Solutions

1. Check that the Coder's encoded type actually matches the value's runtime type.
2. Encode a sample value in a test with CoderUtils.encodeToByteArray(coder, value) to surface the root CoderException cause.
3. Fix the custom coder or choose the correct coder (e.g. SerializableCoder if the value is Java-serializable).

Example fix

// before
SerializableMatchers.viaCoder(InstantCoder.of()).value(someString);
// after
SerializableMatchers.viaCoder(StringUtf8Coder.of()).value(someString);

try { CoderUtils.encodeToByteArray(coder, value); } catch (CoderException e) { throw new IllegalStateException("Value not encodable by coder", e); }

try { viaCoderMatcher.matches(actual); } catch (RuntimeException e) { if (e.getCause() instanceof CoderException) { /* fix coder/value mismatch */ } }

When it happens

Trigger: Constructing a SerializableViaCoder (via SerializableMatchers.viaCoder) with a value that the given Coder cannot encode — mismatched value type vs coder, null encoding failures, or a coder requiring a context the value violates.

Common situations: Using a Coder for type X with a value of type Y after a refactor; custom coders that fail on particular values (e.g. Avro/Proto coders with invalid data); values that are null for coders without nullable support.

Understand the failure class

Background: json.Marshal / "failed to marshal" errors in Go: why "unsupported type" happens and how to fix it — this error's family across 22 libraries.

Related errors

• cannot encode a null BitSet
• cannot encode a null byte[]
• cannot encode a null Integer
• cannot encode a null Long
• cannot encode a null Short

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

Appendix: source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/testing/SerializableMatchers.java:787

   * is not likely to be a good encoding, so should be used only for tests, where data volume is
   * small and minor costs are not critical.
   */
  private static class SerializableViaCoder<T> implements SerializableSupplier<T> {
    /** Cached value that is not serialized. */
    private transient @Nullable T value;

    /** The bytes of {@link #value} when encoded via {@link #coder}. */
    private byte[] encodedValue;

    private Coder<T> coder;

    public SerializableViaCoder(Coder<T> coder, T value) {
      this.coder = coder;
      this.value = value;
      try {
        this.encodedValue = CoderUtils.encodeToByteArray(coder, value);
      } catch (CoderException exc) {
        throw new RuntimeException("Error serializing via Coder", exc);
      }
    }

    @Override
    public T get() {
      if (value == null) {
        try {
          value = CoderUtils.decodeFromByteArray(coder, encodedValue);
        } catch (CoderException exc) {
          throw new RuntimeException("Error deserializing via Coder", exc);
        }
      }
      return value;
    }
  }

  /**
   * Wraps any array with values that can be encoded via a {@link Coder} to make it {@link

View on GitHub (pinned to 12126d8942)