apache/beam · error · IllegalStateException

Attempt to case match on unknown %s subclass %s

Error message

Attempt to case match on unknown %s subclass %s

What it means

DoFnSignature.Parameter.match() is a closed visitor dispatch: it maps every known Parameter subclass (ElementParameter, TimerParameter, StateParameter, RestrictionTrackerParameter, etc.) to a case. If a Parameter instance is of a type the cases object does not know (or a new Parameter subtype was added without extending the cases), an IllegalStateException is thrown.

Source

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

        return cases.dispatch((TimerFamilyParameter) this);
      } else if (this instanceof TimerIdParameter) {
        return cases.dispatch((TimerIdParameter) this);
      } else if (this instanceof BundleFinalizerParameter) {
        return cases.dispatch((BundleFinalizerParameter) this);
      } else if (this instanceof CausedByDrainParameter) {
        return cases.dispatch((CausedByDrainParameter) this);
      } else if (this instanceof CurrentRecordIdParameter) {
        return cases.dispatch((CurrentRecordIdParameter) this);
      } else if (this instanceof CurrentRecordOffsetParameter) {
        return cases.dispatch((CurrentRecordOffsetParameter) this);
      } else if (this instanceof FireTimestampParameter) {
        return cases.dispatch((FireTimestampParameter) this);
      } else if (this instanceof ValueKindParameter) {
        return cases.dispatch((ValueKindParameter) this);
      } else if (this instanceof KeyParameter) {
        return cases.dispatch((KeyParameter) this);
      } else {
        throw new IllegalStateException(
            String.format(
                "Attempt to case match on unknown %s subclass %s",
                Parameter.class.getCanonicalName(), this.getClass().getCanonicalName()));
      }
    }

    /** An interface for destructuring a {@link Parameter}. */
    public interface Cases<ResultT> {
      ResultT dispatch(StartBundleContextParameter p);

      ResultT dispatch(FinishBundleContextParameter p);

      ResultT dispatch(ProcessContextParameter p);

      ResultT dispatch(ElementParameter p);

      ResultT dispatch(SchemaElementParameter p);

View on GitHub (pinned to 12126d8942)

Solutions

1. Extend the cases object to dispatch the unknown Parameter subclass (implement its dispatch method)
2. If you vendored/patched this code, re-sync with the upstream Beam version that introduced the new Parameter type
3. File a bug with the concrete subclass name in the message if it appears with an unmodified Beam version

Example fix

// before
// cases implements dispatch(ElementParameter), dispatch(TimerParameter)... missing new kind
// after
class MyCases implements Parameter.Cases<ReturnT> {
  public ReturnT dispatch(NewParameter p) { return handleNew(p); }
  ...
}

if (param.getClass().getCanonicalName().startsWith("org.apache.beam.sdk.transforms.reflect.DoFnSignature$")) {
  // known Parameter subtype; ensure cases implements its dispatch
}

boolean isKnownParameter(DoFnSignature.Parameter p) {
  return p instanceof DoFnSignature.ElementParameter
      || p instanceof DoFnSignature.TimerParameter
      || p instanceof DoFnSignature.StateParameter
      || p instanceof DoFnSignature.KeyParameter;
}

try {
  return param.match(cases);
} catch (IllegalStateException e) {
  log.error("Unknown Parameter subclass: {}", e.getMessage());
  throw e;
}

When it happens

Trigger: Adding a new Parameter subclass to DoFnSignature without updating all match() call sites; constructing a custom Parameter subtype; an internal bug where a cases object implements only a subset of dispatch methods.

Common situations: Upgrading Apache Beam and vendoring a custom DoFnSignature visitor that now misses new parameter kinds; library development/patching of the reflection package.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Internal error: unexpected kind of Type:
• Internal error initializing BeamFnDataReadRunner: invalid mo
• Timing number 0b" + timingNumber.toString(2) + " has more th
• No proto encoding for PaneInfoCoder, always part of Windowed
• Runner does not support draining.

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