apache/beam · error · UnsupportedOperationException

Cannot outputWithTimestamp from SplitRestriction

Error message

Cannot outputWithTimestamp from SplitRestriction

What it means

In the Splittable DoFn sizing flow, the receiver handed to the SplitRestriction phase does not support element output. Beam's split restriction callback only produces new restrictions; emitting elements there is meaningless to the model, so outputWithTimestamp unconditionally throws UnsupportedOperationException.

Solutions

1. Remove any output calls from @SplitRestriction; it must only yield new restrictions via OutputReceiver.output(restriction).
2. Emit actual elements only in @ProcessElement using the ProcessElements/ restriction tracker receiver.
3. Refactor logic so splitRestriction performs no side effects other than restriction output.

Example fix

// before
@SplitRestriction void split(Restriction r, OutputReceiver<Restriction> out) { out.outputWithTimestamp(r, now); }
// after
@SplitRestriction void split(Restriction r, OutputReceiver<Restriction> out) { out.output(r); }

boolean isSplitRestrictionReceiver = receiver instanceof SplittableSplitAndSizeRestrictionsDoFnRunner.SplitRestrictionReceiver; // do not emit if true

try { out.outputWithTimestamp(r, ts); } catch (UnsupportedOperationException e) { LOG.error("Emitting from splitRestriction is unsupported"); }

When it happens

Trigger: Calling outputWithTimestamp (or output) on the OutputReceiver available inside a @SplitRestriction method of a Splittable DoFn.

Common situations: Developers migrating a DoFn to Splittable DoFn try to emit results during splitRestriction instead of only yielding restrictions; copy-paste of output calls from processElement.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Cannot outputWindowedValue from TruncateRestriction
• Cannot outputWithTimestamp from TruncateRestriction
• RecordId unsupported in
• RecordOffset unsupported in
• Restriction unsupported in

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

Appendix: source

Thrown at sdks/java/harness/src/main/java/org/apache/beam/fn/harness/SplittableSplitAndSizeRestrictionsDoFnRunner.java:469

    @Override
    public Object restriction() {
      return getCurrentRestriction();
    }

    @Override
    public RestrictionTracker<?, ?> restrictionTracker() {
      return getCurrentTracker();
    }

    @Override
    public PipelineOptions pipelineOptions() {
      return pipelineOptions;
    }

    @Override
    public void outputWithTimestamp(RestrictionT output, Instant timestamp) {
      throw new UnsupportedOperationException("Cannot outputWithTimestamp from SplitRestriction");
    }
  }
}

View on GitHub (pinned to 12126d8942)