apache/beam · error · IllegalStateException

This SDK is only capable of dealing with %s materializations

Error message

This SDK is only capable of dealing with %s materializations but was asked to handle %s for PCollectionView with tag %s.

What it means

FnApiStateAccessor.get materializes side inputs according to a materialization URN advertised by the runner. The SDK harness only supports ITERABLE_MATERIALIZATION_URN and MULTIMAP_MATERIALIZATION_URN; if the runner requests any other materialization type (e.g. multimap-with-keys-values or a newer URN), get throws this IllegalStateException naming the requested URN and the PCollectionView tag.

Source

Thrown at sdks/java/harness/src/main/java/org/apache/beam/fn/harness/state/FnApiStateAccessor.java:381

            .setSideInputId(tag.getId())
            .setWindow(encodedWindow);
        break;

      case Materializations.MULTIMAP_MATERIALIZATION_URN:
        checkState(
            sideInputSpec.getCoder() instanceof KvCoder,
            "Expected %s but received %s.",
            KvCoder.class,
            sideInputSpec.getCoder().getClass());
        cacheKeyBuilder
            .getMultimapKeysSideInputBuilder()
            .setTransformId(ptransformId)
            .setSideInputId(tag.getId())
            .setWindow(encodedWindow);
        break;

      default:
        throw new IllegalStateException(
            String.format(
                "This SDK is only capable of dealing with %s materializations "
                    + "but was asked to handle %s for PCollectionView with tag %s.",
                ImmutableList.of(
                    Materializations.ITERABLE_MATERIALIZATION_URN,
                    Materializations.MULTIMAP_MATERIALIZATION_URN),
                sideInputSpec.getAccessPattern(),
                tag));
    }
    return (T)
        stateKeyObjectCache.computeIfAbsent(
            cacheKeyBuilder.build(),
            key -> {
              switch (sideInputSpec.getAccessPattern()) {
                case Materializations.ITERABLE_MATERIALIZATION_URN:
                  return sideInputSpec
                      .getViewFn()
                      .apply(

View on GitHub (pinned to 12126d8942)

Solutions

1. Upgrade the Apache Beam SDK harness so it supports the materialization URN reported in the message.
2. Downgrade or reconfigure the runner to advertise only supported materializations (iterable/multimap).
3. Check runner capability flags (e.g. multimap keys-values side inputs) and disable them if the SDK cannot handle them.
4. Align runner and SDK versions so capability negotiation succeeds.

Example fix

// before: runner advertises a materialization the harness cannot handle
runnerCapabilities.add(MULTIMAP_KEYS_VALUES_SIDE_INPUT);
// after: only enable capabilities the SDK harness supports
// (upgrade harness first, then enable the capability)

Set<String> supported = Set.of("beam:runner_api:v:iterable_side_input", "beam:runner_api:v:multimap_side_input");
if (!supported.contains(materializationUrn)) {
  throw new UnsupportedOperationException("Upgrade SDK harness to handle " + materializationUrn);
}

When it happens

Trigger: Calling sideInput() on a PCollectionView whose runner-side side input is configured with an unsupported materialization URN in the process-bundle instruction.

Common situations: Runner/SDK version mismatch introducing a new materialization type; custom or newer runner enabling MULTIMAP_KEYS_VALUES side inputs against an older harness; misconfigured runner capabilities negotiation.

Related errors

• Unknown state key type requested %s.
• Unknown context parameter: ${param.parDoParamName}
• Unsupported window mapping fn: ${sideInput.windowMappingFn.u
• State stream is closed.
• Outbound data endpoint already registered for

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