apache/beam · error · IllegalArgumentException

Could not encode the default value %s with the provided code

Error message

Could not encode the default value %s with the provided coder %s

What it means

When View.asSingleton(defaultValue) supplies a default, SingletonCombineFn eagerly encodes the default with the input PCollection's coder via CoderUtils.encodeToByteArray to store it safely. If the coder cannot encode the default (CoderException), Beam throws IllegalArgumentException stating the value and coder that failed. This catches coder/value mismatches at pipeline construction.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/View.java:530

  }

  private static class SingletonCombineFn<T> extends Combine.BinaryCombineFn<T> {
    private final boolean hasDefault;
    private final @Nullable Coder<T> valueCoder;
    private final byte @Nullable [] defaultValue;

    private SingletonCombineFn(boolean hasDefault, Coder<T> coder, T defaultValue) {
      this.hasDefault = hasDefault;
      if (hasDefault) {
        if (defaultValue == null) {
          this.defaultValue = null;
          this.valueCoder = coder;
        } else {
          this.valueCoder = coder;
          try {
            this.defaultValue = CoderUtils.encodeToByteArray(coder, defaultValue);
          } catch (CoderException e) {
            throw new IllegalArgumentException(
                String.format(
                    "Could not encode the default value %s with the provided coder %s",
                    defaultValue, coder));
          }
        }
      } else {
        this.valueCoder = null;
        this.defaultValue = null;
      }
    }

    @Override
    public T apply(T left, T right) {
      throw new IllegalArgumentException(
          "PCollection with more than one element "
              + "accessed as a singleton view. Consider using Combine.globally().asSingleton() to "
              + "combine the PCollection into a single value");
    }

View on GitHub (pinned to 12126d8942)

Solutions

1. Ensure the default value's type matches the PCollection's element type and coder
2. Test the coder with CoderUtils.encodeToByteArray(coder, defaultValue) before use
3. Use a coder that supports the default (e.g. nullable coder like NullableCoder.of) or fix a custom coder's encode method

Example fix

// before
PCollectionView<String> view = input.apply(View.asSingleton(null)); // coder cannot encode null
// after
PCollectionView<String> view = input.setCoder(NullableCoder.of(StringUtf8Coder.of()))
    .apply(View.asSingleton(null));

try { CoderUtils.encodeToByteArray(coder, defaultValue); } catch (CoderException e) { /* fix coder/default mismatch before View.asSingleton(default) */ }

try { view = input.apply(View.asSingleton(defaultValue)); } catch (IllegalArgumentException e) { throw new IllegalStateException("Default value not encodable by PCollection coder", e); }

When it happens

Trigger: Calling View.asSingleton(default) where the PCollection's Coder cannot encode `default` — e.g. the coder is for a different type than the default value, the default is null with a non-nullable coder, or a custom coder's encode() throws for that value.

Common situations: Mismatches between coder inferred for the PCollection and the default value type; nulls passed with a coder that rejects null; custom Coder implementations that throw on encode for edge-case values; pipeline refactor changed the element type but the default remained old-typed.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• ApproximateUnique.PerKey requires its input to use KvCoder
• 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/5182fa76da429b94. Report an issue: GitHub.