apache/beam · error · java.lang.RuntimeException

Exception thrown when outputting WindowedValue

Error message

Exception thrown when outputting WindowedValue

What it means

WindowedValue.OutputWindowedValue.output() wraps any checked exception thrown by the receiver or the value builder into a RuntimeException with this message. Beam throws it because DoFn output delivery failed downstream (encoding, windowing, or receiver logic), and the original checked exception is preserved as the cause.

Solutions

1. Inspect the 'Caused by' chain to find the real underlying exception and fix it
2. Fix the Coder for the emitted value so encode() does not throw IOException
3. Ensure the receiver is set via setReceiver() before output() and does not throw checked exceptions
4. If the cause is a serializable-mismatch, verify the element type has a registered Coder

Example fix

// before: emit custom type without registered coder causing IOException downstream
context.output(myCustomRecord);
// after: register a Coder for the element type
pipeline.getCoderRegistry().registerCoderForClass(MyCustomRecord.class, MyCustomRecordCoder.of());

if (receiver == null) throw new IllegalStateException("call setReceiver() before output()");

try { outputWindowedValue.output(value); } catch (RuntimeException e) { Throwable cause = e.getCause(); log.error("WindowedValue output failed: {}", cause != null ? cause.getMessage() : e.getMessage(), e); throw e; }

When it happens

Trigger: Calling output() on a WindowedValue.OutputWindowedValue whose set value builder or receiver throws a checked Exception that is not a RuntimeException; typically the element's encoded form fails or the receiver's own logic throws IOException.

Common situations: A DoFn emitting a value whose Coder throws IOException during serialization; a custom WindowedValueReceiver throwing a checked exception; pipeline failures during bundle processing where the real cause is in the stack trace's 'Caused by'.

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

• cannot encode a null Count-min Sketch
• cannot encode a null HyperLogLogPlus sketch
• cannot encode a null Integer
• cannot encode a null PredictionResult
• cannot encode a null SolrDocument

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

Appendix: source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/values/WindowedValues.java:262

    }

    @Override
    @Pure
    public <OtherT> Builder<OtherT> withValue(OtherT newValue) {
      // because of erasure, this type system lie is safe
      return ((Builder<OtherT>) builder(this)).setValue(newValue);
    }

    @Override
    public void output() {
      try {
        checkStateNotNull(receiver, "A WindowedValueReceiver must be set via setReceiver()")
            .output(build());
      } catch (Exception exc) {
        if (exc instanceof RuntimeException) {
          throw (RuntimeException) exc;
        } else {
          throw new RuntimeException("Exception thrown when outputting WindowedValue", exc);
        }
      }
    }

    public WindowedValue<T> build() {
      return WindowedValues.of(
          getValue(),
          getTimestamp(),
          getWindows(),
          getPaneInfo(),
          getRecordId(),
          getRecordOffset(),
          causedByDrain(),
          getOpenTelemetryContext(),
          getValueKind());
    }

    @Override

View on GitHub (pinned to 12126d8942)