{"record":{"id":"1d3867a94416c7f4","repo":"apache/beam","slug":"pcollection-with-more-than-one-element-accessed-as-a-1d3867","errorCode":null,"errorMessage":"PCollection with more than one element accessed as a singleton view.","messagePattern":"PCollection with more than one element accessed as a singleton view\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/values/PCollectionViews.java","lineNumber":549,"sourceCode":"        }\n        return defaultValue;\n      }\n    }\n\n    @Override\n    public Materialization<IterableView<T>> getMaterialization() {\n      return Materializations.iterable();\n    }\n\n    @Override\n    public T apply(IterableView<T> primitiveViewT) {\n      Iterator<T> iterator = primitiveViewT.get().iterator();\n      if (!iterator.hasNext()) {\n        return getDefaultValue();\n      }\n      T result = iterator.next();\n      if (iterator.hasNext()) {\n        throw new IllegalArgumentException(\n            \"PCollection with more than one element accessed as a singleton view.\");\n      }\n      return result;\n    }\n\n    @Override\n    public TypeDescriptor<T> getTypeDescriptor() {\n      return typeDescriptorSupplier.get();\n    }\n  }\n\n  @Internal\n  public interface HasDefaultValue<T> {\n    T getDefaultValue();\n  }\n\n  @Internal\n  public interface IsSingletonView<T> {}","sourceCodeStart":531,"sourceCodeEnd":567,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/values/PCollectionViews.java#L531-L567","documentation":"SingletonViewFn2.apply enforces the singleton contract: it returns the single element, falls back to getDefaultValue() if the PCollection is empty, and throws IllegalArgumentException when the PCollection contains more than one element. Beam's View.asSingleton() semantics only permit zero-or-one elements per window, so multiple elements are a programming error.","triggerScenarios":"Creating a singleton view with View.asSingleton() over a PCollection that emits two or more elements in a window and then reading it via sideInput() inside a DoFn.","commonSituations":"Forgetting a Combine/combiner (e.g. Mean.globally(), First.of()) before View.asSingleton(); windowed pipelines where the view is per-window and some windows receive multiple records; deduplicated joins producing multiple matches.","solutions":["Apply a global combine before the view: pc.apply(Mean.globally()).apply(View.asSingleton()).","If per-window, make the view window-aware semantics explicit: with the combine fn applied per window, or use View.asMap()/asList() and iterate.","Deduplicate/select one element upstream (First.of, Sample.any(1), or a distinct) so at most one element remains.","If multiple values are valid, switch the API to a mapping view and access via sideInput(view).get(key)."],"exampleFix":"// before\nPCollectionView<Integer> threshold = pc.apply(View.asSingleton());\n// after\nPCollectionView<Integer> threshold = pc.apply(Mean.globally()).apply(View.asSingleton());","handlingStrategy":"validation","validationCode":"long n = pc.apply(Count.globally()).apply(Maybe.first()); // or reason statically\n// Prefer: apply a global combine before asSingleton()\nPCollectionView<T> view = pc.apply(Combine.globally(fn)).apply(View.asSingleton());","typeGuard":null,"tryCatchPattern":"try {\n  T v = c.sideInput(singletonView);\n} catch (IllegalArgumentException e) {\n  if (e.getMessage().contains(\"more than one element\")) { /* switch to asMap/asList */ }\n  throw e;\n}","preventionTips":["Never call View.asSingleton() directly on raw records — always aggregate first.","In windowed pipelines, confirm each window yields at most one element.","Choose asList/asMap views when multiplicity is possible."],"tags":["java","apache-beam","singleton-view","illegal-argument"],"backgroundTag":"invalid-argument-value","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}