apache/beam · error · UnsupportedOperationException

Schema element unsupported in ${context}

Error message

Schema element unsupported in ${context}

What it means

This UnsupportedOperationException is thrown by DoFnInvoker.BaseArgumentProvider.schemaElement when a schema-element parameter is requested in a DoFn invocation context that cannot resolve it. Schema elements (fields of the current row when the DoFn operates on a schema'd type, bound via @SchemaElementIndex) are only supplied by contexts that process schema rows; the base provider always throws as a guard. getErrorContext() names the invocation context in the message.

Source

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

      throw new UnsupportedOperationException(
          "Cannot access key as parameter outside of @OnTimer method.");
    }

    @Override
    public @Nullable Object sideInput(String tagId) {
      throw new UnsupportedOperationException(
          String.format("SideInput unsupported in %s", getErrorContext()));
    }

    @Override
    public TimerMap timerFamily(String tagId) {
      throw new UnsupportedOperationException(
          String.format("TimerFamily unsupported in %s", getErrorContext()));
    }

    @Override
    public @Nullable Object schemaElement(int index) {
      throw new UnsupportedOperationException(
          String.format("Schema element unsupported in %s", getErrorContext()));
    }

    @Override
    public Instant timestamp(DoFn<InputT, OutputT> doFn) {
      throw new UnsupportedOperationException(
          String.format("Timestamp unsupported in %s", getErrorContext()));
    }

    @Override
    public @Nullable String currentRecordId(DoFn<InputT, OutputT> doFn) {
      throw new UnsupportedOperationException(
          String.format("RecordId unsupported in %s", getErrorContext()));
    }

    @Override
    public @Nullable Long currentRecordOffset(DoFn<InputT, OutputT> doFn) {
      throw new UnsupportedOperationException(

View on GitHub (pinned to 12126d8942)

Solutions

1. Move the @SchemaElementIndex parameter onto the @ProcessElement method so it is resolved by the process-element ArgumentProvider.
2. Ensure the input PCollection's type has a registered schema (SchemaRegistry / @DefaultSchema annotation) so the runner supplies schema elements.
3. Access the full element via the element parameter and read fields directly if schema binding is not required.
4. If implementing a custom ArgumentProvider, override schemaElement(int) to return the field value for the current row.

Example fix

// before
@StartBundle
public void startBundle(StartBundleContext c, @SchemaElementIndex(0) String id) { // throws
}

// after
@ProcessElement
public void processElement(ProcessContext c, @SchemaElementIndex(0) String id) {
  handle(c, id);
}

// Ensure the input type has a registered schema and schema params are on @ProcessElement only.
Schema s = pcollection.getSchema();
if (s == null) throw new IllegalArgumentException("Input type has no schema; @SchemaElementIndex params unsupported");

if (context instanceof DoFn.ProcessContext && pcollection.getSchema() != null) {
  // schema element binding is supported
}

try {
  bindSchemaElements();
} catch (UnsupportedOperationException e) {
  // fall back to reading fields from the full element object
}

When it happens

Trigger: Binding an @SchemaElementIndex-annotated parameter or calling schemaElement(index) in a context whose ArgumentProvider does not override it, e.g. @StartBundle, @FinishBundle, @OnTimer methods, or when the input type has no schema so the runner-provided ArgumentProvider never overrides schemaElement(int).

Common situations: Declaring schema-element parameters on lifecycle methods like @StartBundle instead of @ProcessElement; using a DoFn over a POJO/Row without a registered schema so the invoker falls back to the base provider; custom test ArgumentProviders extending BaseArgumentProvider without overriding schemaElement.

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

• Parameter has no schema and the input is not a simple type.
• Parameter has no schema and the input is not a primitive typ
• Not expected to access Restriction from a regular DoFn in Do
• Not expected to access RestrictionTracker from a regular DoF
• SideInput unsupported in ${context}

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