apache/beam · error · Error

Expected a single element, got

Error message

Expected a single element, got ${asArray.length}

What it means

This error is thrown by a singleton side input view in pardo.ts when the side input PCollection materialized to a list whose length is neither 0 nor 1. A singleton side input (via pvalue.AsSingleton) promises exactly one element per window; if the underlying PCollection emits more than one element in the current window, the view cannot pick one, so the library throws. Empty lists are allowed only when a defaultValue was supplied.

Solutions

  1. Pass a defaultValue to AsSingleton only if empty is acceptable — it does not fix multi-element cases.
  2. Filter or dedupe the side-input PCollection so it produces exactly one element per window (e.g. pardo.Map or Combine to a single value).
  3. Use AsIter or AsMultimap side inputs if multiple elements per window are legitimate.
  4. Add logging/counting before the pipeline stage to confirm the side input's element count per window.

Example fix

// before
const threshold = context.requireSideInput(pvalue.AsSingleton(scores));

// after: guarantee exactly one element per window
const maxScore = scores.apply("max", combiners.Combine(CombineFns.maxFn()));
const threshold = context.requireSideInput(pvalue.AsSingleton(maxScore));
Defensive patterns

Strategy: validation

Validate before calling

// ensure the side input yields one element per window before use
const count = await beam.pvalue.AsSingleton && /* design-time: */
// dedupe/combine upstream so exactly one element remains per window
const single = elems.apply("toSingle", beam.combiners.Combine(fn => fn.maxBy(x => x.ts)));

Prevention

When it happens

Trigger: Calling `pcoll.applyAsSideInput()` / `context.requireSideInput(AsSingleton(pcoll))` when the side-input PCollection emits 2+ elements in a window, and no defaultValue was given.

Common situations: Developers assume a key/window has one record but it actually has several (e.g. joining a one-row-per-user PCollection where a duplicate user exists, or applying AsSingleton to an unfiltered multi-element collection).

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

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

Appendix: source

Thrown at sdks/typescript/src/apache_beam/transforms/pardo.ts:432

export function singletonSideInput<T>(
  pcoll: PCollection<T>,
  defaultValue: T | undefined = undefined,
): SideInputParam<T, Iterable<T>, T> {
  return new SideInputParam<T, Iterable<T>, T>(pcoll, {
    accessPattern: "beam:side_input:iterable:v1",
    toValue: (iter: Iterable<T>) => {
      const asArray = Array.from(iter);
      if (
        asArray.length === 0 &&
        defaultValue !== null &&
        defaultValue !== undefined
      ) {
        return defaultValue;
      } else if (asArray.length === 1) {
        return asArray[0];
      } else {
        throw new Error("Expected a single element, got " + asArray.length);
      }
    },
  });
}

// TODO: (Extension) Map side inputs.

/**
 * The superclass of all metric accessors, such as counters and distributions.
 */
export class Metric<T> extends ParDoUpdateParam<T> {
  constructor(
    readonly metricType: string,
    readonly name: string,
  ) {
    super("metric");
  }
}

View on GitHub (pinned to 12126d8942)