apache/beam · error · IllegalStateException

Unknown state key type requested %s.

Error message

Unknown state key type requested %s.

What it means

FnApiStateAccessor's cache selection logic switches over the StateKey protocol type to decide which cache (process-wide vs bundle) backs a state cell. If the StateKey oneof is a type it does not recognize, it throws this IllegalStateException with the key's string form. This means the runner sent a state key type the harness cannot cache.

Source

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

          if (!token.hasSideInput()) {
            continue;
          }
          if (stateKey
                  .getMultimapKeysSideInput()
                  .getTransformId()
                  .equals(token.getSideInput().getTransformId())
              && stateKey
                  .getMultimapKeysSideInput()
                  .getSideInputId()
                  .equals(token.getSideInput().getSideInputId())) {
            // IDEA: If cachetoken shows up on profiles, create a simpler type to weigh like
            // UserStateCacheTokenKey.
            return Caches.subCache(processWideCache, token, stateKey);
          }
        }
        break;
      default:
        throw new IllegalStateException(
            String.format("Unknown state key type requested %s.", stateKey));
    }
    // The default is to use the bundle cache.
    return Caches.subCache(bundleCache.get(), stateKey);
  }

  private <T> BagUserState<T> createBagUserState(StateKey stateKey, Coder<T> valueCoder) {
    BagUserState<T> rval =
        new BagUserState<>(
            getCacheFor(stateKey),
            beamFnStateClient,
            processBundleInstructionId.get(),
            stateKey,
            valueCoder);
    stateFinalizers.add(rval::asyncClose);
    return rval;
  }

View on GitHub (pinned to 12126d8942)

Solutions

1. Upgrade the Beam SDK harness so its StateKey switch knows the reported key type.
2. Check the printed stateKey in the message and map it to the runner feature that produced it; disable that feature.
3. Ensure runner and SDK versions match and workers were restarted after upgrade.
4. File/consult a Beam issue if the key type is a standard one supported in newer releases.

Example fix

// before: mixed versions (runner 2.60, harness 2.40 image)
--sdk_harness_container_image=old-image
// after
--sdk_harness_container_image=gcr.io/.../beam_sdk_harness:<matching-runner-version>

try {
  // state access
} catch (IllegalStateException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Unknown state key type")) {
    LOG.error("Runner sent unsupported StateKey {} — upgrade harness", e.getMessage());
  } else { throw e; }
}

When it happens

Trigger: The runner issues a state request whose StateKey is not one of the handled types (bag, multimap, user multimap, iterable side input, multimap side input, channel/appendable, watermark handled upstream, custom user state) — typically a newly added or runner-specific StateKey variant.

Common situations: Runner and SDK harness version skew where the runner uses a newer StateKey proto field; experimental runner features sending unknown state key types.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• This SDK is only capable of dealing with %s materializations
• Unknown context parameter: ${param.parDoParamName}
• State stream is closed.
• Outbound data endpoint already registered for
• Cannot access state in non-window observing context.

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