apache/beam · error · java.lang.IllegalArgumentException

Unknown time domain

Error message

Unknown time domain

What it means

This is the switch default in timerFamilyTimeDomainToProto: if the TimeDomain enum value is neither EVENT_TIME, PROCESSING_TIME, nor SYNCHRONIZED_PROCESSING_TIME, Beam has no proto mapping and throws a bare IllegalArgumentException('Unknown time domain'). It guards against future/unknown enum constants.

Solutions

1. Ensure the timer's TimeDomain is a valid supported constant: EVENT_TIME or PROCESSING_TIME
2. Upgrade all Beam SDK modules to the same version so enum constants match
3. Null-check the TimeDomain before building the TimerFamilySpec

Objects.requireNonNull(timeDomain, "timeDomain must not be null");
Preconditions.checkArgument(timeDomain == TimeDomain.EVENT_TIME || timeDomain == TimeDomain.PROCESSING_TIME, "unsupported time domain %s", timeDomain);

boolean isValidTimeDomain(TimeDomain d) { return d != null && (d == TimeDomain.EVENT_TIME || d == TimeDomain.PROCESSING_TIME || d == TimeDomain.SYNCHRONIZED_PROCESSING_TIME); }

try { ParDoTranslation.timerFamilyTimeDomainToProto(domain); } catch (IllegalArgumentException e) { /* default the timer to EVENT_TIME */ }

When it happens

Trigger: Translating a timer family spec whose TimeDomain is null or an unrecognized enum constant (e.g. a newer Beam adding a TimeDomain that an older translating SDK cannot map, or a programmatically built spec passing null).

Common situations: Version-skew between SDK components; reflection-based or generated code passing an unexpected value; custom TimeDomain implementations.

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 access fire timestamp outside of @OnTimer method.
• Cannot access OnTimerContext outside of @OnTimer methods.
• Cannot access time domain outside of @ProcessTimer method.
• Cannot access timer in non-window observing context.
• Cannot access timerFamily in non-window observing context.

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

Appendix: source

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

        .setTimeDomain(translateTimeDomain(timer.getTimeDomain()))
        .setTimerFamilyCoderId(
            registerCoderOrThrow(components, Timer.Coder.of(keyCoder, windowCoder)))
        .build();
  }

  public static RunnerApi.TimeDomain.Enum translateTimeDomain(TimeDomain timeDomain) {
    switch (timeDomain) {
      case EVENT_TIME:
        return RunnerApi.TimeDomain.Enum.EVENT_TIME;
      case PROCESSING_TIME:
        return RunnerApi.TimeDomain.Enum.PROCESSING_TIME;
      case SYNCHRONIZED_PROCESSING_TIME:
        throw new IllegalArgumentException(
            String.format(
                "%s is not permitted for user timers",
                TimeDomain.SYNCHRONIZED_PROCESSING_TIME.name()));
      default:
        throw new IllegalArgumentException("Unknown time domain");
    }
  }

  public static FunctionSpec translateDoFn(
      DoFn<?, ?> fn,
      TupleTag<?> tag,
      Map<String, PCollectionView<?>> sideInputMapping,
      DoFnSchemaInformation doFnSchemaInformation,
      SdkComponents components) {
    return FunctionSpec.newBuilder()
        .setUrn(CUSTOM_JAVA_DO_FN_URN)
        .setPayload(
            ByteString.copyFrom(
                SerializableUtils.serializeToByteArray(
                    DoFnWithExecutionInformation.of(
                        fn, tag, sideInputMapping, doFnSchemaInformation))))
        .build();
  }

View on GitHub (pinned to 12126d8942)