apache/beam · error · IllegalArgumentException

Empty PCollection accessed as a singleton view. Consider…

Error message

Empty PCollection accessed as a singleton view. Consider setting withDefault to provide a default value

What it means

This error is thrown when an empty PCollection is accessed through a singleton PCollectionView that was not given a default value via withDefault(). Since there are no elements to extract a singleton from and no fallback default, Beam throws an IllegalArgumentException at access time to prevent silently producing a null or undefined value.

Solutions

1. Add .withDefault(defaultValue) to the View.asSingleton() builder
2. Use View.asList() or View.asMap() if the input may legitimately be empty or have multiple elements
3. Ensure the upstream PCollection is guaranteed non-empty (e.g. Validate upstream logic or add a fallback element)
4. Catch IllegalArgumentException around sideInput access and handle the empty case explicitly

Example fix

// before
PCollectionView<Integer> view = pc.apply(View.asSingleton());
// after
PCollectionView<Integer> view = pc.apply(View.asSingleton().withDefault(0));

// Guard: check emptiness before creating a singleton view, or always supply a default
if (pc.getTypeDescriptor() != null && mayBeEmpty) {
  view = pc.apply(View.asSingleton().withDefault(defaultValue));
}

try { T v = c.sideInput(view); } catch (IllegalArgumentException e) { T v = fallbackValue; }

When it happens

Trigger: Building View.asSingleton() without withDefault(...) on a PCollection that turns out to be empty, then accessing the view via sideInput() inside a DoFn/ParDo. Common with filtered inputs (e.g. filter(predicate)) that can legally produce zero elements.

Common situations: A filter or early-exit branch produces an empty PCollection in production but not in testing; using asSingleton() on data that is not guaranteed to have exactly one element (should be asList/asMap instead).

Related errors

• buildDescriptor: failed to handle coder on stage
• calling getSideInput() with unknown view
• calling getSideInput() with unknown view
• Cannot access sideInput in non-window observing context.
• Could not decode the default value with the provided coder

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

Appendix: source

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

              + "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));
        }
      } else {
        throw new IllegalArgumentException(
            "Empty PCollection accessed as a singleton view. "
                + "Consider setting withDefault to provide a default value");
      }
    }
  }

  /**
   * <b><i>For internal use only; no backwards-compatibility guarantees.</i></b>
   *
   * <p>Public only so a {@link PipelineRunner} may override its behavior.
   *
   * <p>See {@link View#asMultimap()}.
   */
  @Internal
  public static class AsMultimap<K, V>
      extends PTransform<PCollection<KV<K, V>>, PCollectionView<Map<K, Iterable<V>>>> {
    private final boolean inMemory;

View on GitHub (pinned to 12126d8942)