apache/beam · error · IllegalArgumentException

PCollection with more than one element accessed as a…

Error message

PCollection with more than one element accessed as a singleton view. Consider using Combine.globally().asSingleton() to combine the PCollection into a single value

What it means

View.asSingleton() (withoutDefaults) uses SingletonCombineFn as a Combine function; its merge/apply method deliberately throws IllegalArgumentException when it is actually invoked with two elements, meaning the underlying PCollection had more than one element at combine time but was accessed as a singleton. It suggests using Combine.globally().asSingleton() to explicitly reduce, or providing a default / using other views.

Solutions

Reduce the PCollection to a single element with Combine.globally(...).asSingleton() before viewing
Use View.asList() or View.asIterable() if multiple elements are legitimate
Ensure the upstream logic (filter/top) guarantees exactly one element per window
Provide a default with asSingleton(default) if single-element semantics are not guaranteed

Example fix

// before
PCollectionView<Integer> maxView = numbers.apply(View.asSingleton()); // throws if >1 element
// after
PCollectionView<Integer> maxView = numbers
    .apply(Combine.globally(Max.ofIntegers()))
    .apply(View.asSingleton());

Defensive patterns

Strategy: try-catch

Validate before calling

// Before viewing, guarantee single element:
PCollectionView<T> safeView = input.apply(Combine.globally(firstOrNull)).apply(View.asSingleton());

Try / catch

try { sideValue = c.sideInput(singletonView); } catch (IllegalArgumentException e) { LOG.error("Singleton view had multiple elements; use Combine.globally().asSingleton() or View.asList()", e); throw e; }

Prevention

Never assume a filter yields exactly one element; enforce with Combine.globally
Use View.asList()/asIterable() when multiplicity is possible
Ensure windows align so only one element per window reaches the side input
Add a default via asSingleton(default) when emptiness is possible

When it happens

Trigger: Accessing a PCollectionView built with View.asSingleton() (no default) while the side-input PCollection contains 2+ elements at evaluation time in the window; the combine's apply() is called with (left, right) and throws.

Common situations: Assuming an upstream filter produced exactly one element but it produced many; missing window alignment so multiple elements land in one window; datasets growing over time to include more than the assumed single record (e.g. 'latest config' row duplicated); using asSingleton instead of asList/Combine.globally on multi-element data.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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

Appendix: source

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

          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");
    }

    @Override
    public T identity() {
      if (hasDefault) {
        if (defaultValue == null) {
          return null;
        }
        try {
          return CoderUtils.decodeFromByteArray(valueCoder, defaultValue);
        } catch (CoderException e) {
          throw new IllegalArgumentException(
              String.format(
                  "Could not decode the default value with the provided coder %s", valueCoder));
        }

View on GitHub (pinned to 12126d8942)