apache/beam · error · java.lang.IllegalArgumentException

Unknown

Error message

Unknown %s: %s

What it means

ParDoTranslation.stateSpecFromProto converts a RunnerApi.StateSpec oneof (BAG_SPEC, ORDERED_LIST_SPEC, COMBINING_SPEC, etc.) into the Java StateSpecs API. SPEC_NOT_SET or an unrecognized case means the proto carries no known state spec, so translation cannot proceed and throws this IllegalArgumentException.

Solutions

1. Align Beam versions between graph construction and translation so all state spec variants are known
2. Inspect the RunnerApi proto and ensure the state spec oneof is set to a supported case (bag, map, set, combining, ordered list)
3. Rebuild the pipeline from source instead of reusing a saved/dumped proto

if (stateSpec.getStateSpecCase() == RunnerApi.StateSpec.StateSpecCase.SPEC_NOT_SET) throw new IllegalArgumentException("state spec oneof unset");

boolean hasKnownStateSpec(RunnerApi.StateSpec s) { return s.getStateSpecCase() != RunnerApi.StateSpec.StateSpecCase.SPEC_NOT_SET; }

try { return ParDoTranslation.stateSpecFromProto(spec, components); } catch (IllegalArgumentException e) { log.error("state spec case {} unsupported", spec.getStateSpecCase(), e); throw e; }

When it happens

Trigger: Translating a graph whose StateSpec message has the oneof unset (SPEC_NOT_SET) — e.g. a partially built or truncated proto, or a newer Beam writing a state spec variant this older SDK cannot map.

Common situations: Version-skew between the job-submission SDK and the runtime/expansion SDK; hand-crafted or mutated pipeline protos; corrupted pipeline JSON round-trips.

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

• Cannot create from non-Java
• Failed to encode key for multimap user state id
• Malformed class : state declaration field is not accessible.
• response.get().getError()
• is not permitted for user timers

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

Appendix: source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/util/construction/ParDoTranslation.java:714

        return StateSpecs.combining(
            (Coder) components.getCoder(stateSpec.getCombiningSpec().getAccumulatorCoderId()),
            combineFn);

      case MAP_SPEC:
        return StateSpecs.map(
            components.getCoder(stateSpec.getMapSpec().getKeyCoderId()),
            components.getCoder(stateSpec.getMapSpec().getValueCoderId()));

      case SET_SPEC:
        return StateSpecs.set(components.getCoder(stateSpec.getSetSpec().getElementCoderId()));

      case ORDERED_LIST_SPEC:
        return StateSpecs.orderedList(
            components.getCoder(stateSpec.getOrderedListSpec().getElementCoderId()));

      case SPEC_NOT_SET:
      default:
        throw new IllegalArgumentException(
            String.format("Unknown %s: %s", RunnerApi.StateSpec.class.getName(), stateSpec));
    }
  }

  public static String registerCoderOrThrow(SdkComponents components, Coder coder) {
    try {
      return components.registerCoder(coder);
    } catch (IOException exc) {
      throw new RuntimeException("Failure to register coder", exc);
    }
  }

  public static RunnerApi.TimerFamilySpec translateTimerFamilySpec(
      TimerSpec timer,
      SdkComponents components,
      Coder<?> keyCoder,
      Coder<BoundedWindow> windowCoder) {
    return RunnerApi.TimerFamilySpec.newBuilder()

View on GitHub (pinned to 12126d8942)