apache/beam · error · UnsupportedOperationException

RestrictionTracker unsupported in

Error message

RestrictionTracker unsupported in %s

What it means

The stub DoFnInvoker throws UnsupportedOperationException for restrictionTracker(). A RestrictionTracker is only available while invoking splittable-DoFn @ProcessElement methods on runners that support SDF; the base class never provides one.

Solutions

1. Run the SDF on a runner that supports splittable DoFn and use the DoFnInvokers-built invoker
2. Request the RestrictionTracker only via the @ProcessElement method parameter, not directly during other phases
3. Check the DoFnSignature: restrictionTracker support requires @GetInitialRestriction/@SplitRestriction etc.

Example fix

// before
invoker.restrictionTracker(); // throws in non-SDF phases
// after
@ProcessElement
public void process(ProcessContext c, RestrictionTracker<MyRestr, Long> tracker) { ... }

if (signature.trackerT() != null) {
  requireSdfCapableRunner();
}

boolean supportsRestrictionTracker(DoFnInvoker<?, ?> i) {
  return !(i instanceof DoFnInvoker.BaseDoFnInvoker);
}

try {
  tracker = invoker.restrictionTracker();
} catch (UnsupportedOperationException e) {
  throw new IllegalStateException("SDF not supported here", e);
}

When it happens

Trigger: Calling restrictionTracker() on a placeholder invoker, or during a lifecycle phase (finishBundle, onTimer) that has no restriction tracker.

Common situations: Splittable DoFns run on runners without SDF support; test harnesses using the base invoker; accessing the tracker outside the element-processing phase.

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

• RecordId unsupported in
• RecordOffset unsupported in
• Restriction unsupported in
• ValueKind unsupported in
• BoundedWindow unsupported in

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

Appendix: source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/reflect/DoFnInvoker.java:476

      throw new UnsupportedOperationException(
          String.format("State unsupported in %s", getErrorContext()));
    }

    @Override
    public Timer timer(String timerId) {
      throw new UnsupportedOperationException(
          String.format("Timer unsupported in %s", getErrorContext()));
    }

    @Override
    public RestrictionTracker<?, ?> restrictionTracker() {
      throw new UnsupportedOperationException(
          String.format("RestrictionTracker unsupported in %s", getErrorContext()));
    }

    @Override
    public Object watermarkEstimatorState() {
      throw new UnsupportedOperationException(
          String.format("WatermarkEstimatorState unsupported in %s", getErrorContext()));
    }

    @Override
    public WatermarkEstimator<?> watermarkEstimator() {
      throw new UnsupportedOperationException(
          String.format("WatermarkEstimator unsupported in %s", getErrorContext()));
    }

    @Override
    public BundleFinalizer bundleFinalizer() {
      throw new UnsupportedOperationException(
          String.format("BundleFinalizer unsupported in %s", getErrorContext()));
    }

    /**
     * Return a human readable representation of the current call context to be used during error
     * reporting.

View on GitHub (pinned to 12126d8942)