What causes "Unknown time domain: %s" in apache/beam?

apache/beam · error · ValueError

Unknown time domain

Error message

Unknown time domain: %s

What it means

TimeDomain.from_string converts a string/enum value into a TimeDomain enum and raises ValueError when the value is not one of WATERMARK, REAL_TIME, or DEPENDENT_REAL_TIME. The library throws it to fail fast on unrecognized time-domain names in windowing/trigger timer configuration.

Solutions

Use the TimeDomain enum members (TimeDomain.WATERMARK, TimeDomain.REAL_TIME, TimeDomain.DEPENDENT_REAL_TIME) instead of raw strings.
If given a string, map/normalize it to the enum before calling from_string.
Check spelling and case of the domain string against the enum member names.

Example fix

// before
domain = TimeDomain.from_string('processing_time')
// after
domain = TimeDomain.from_string(TimeDomain.REAL_TIME)

Defensive patterns

Strategy: validation

Validate before calling

VALID = {TimeDomain.WATERMARK, TimeDomain.REAL_TIME, TimeDomain.DEPENDENT_REAL_TIME}
assert domain in VALID, f'Unsupported time domain: {domain}'

Type guard

def is_valid_time_domain(d):
    return d in (TimeDomain.WATERMARK, TimeDomain.REAL_TIME, TimeDomain.DEPENDENT_REAL_TIME)

Try / catch

try:
    td = TimeDomain.from_string(domain_str)
except ValueError:
    td = TimeDomain.WATERMARK  # documented default

Prevention

Always use TimeDomain enum members, never raw strings.
Normalize config strings through an explicit mapping dict.
Keep domain values in configs consistent with the enum names of your Beam version.

When it happens

Trigger: Calling TimeDomain.from_string with any string other than the exact enum names, e.g. from_string('processing_time') or from_string('event_time'), instead of the TimeDomain enum members.

Common situations: Hand-written pipeline descriptions or runner-internal configs that store time domains as free-form strings; typos in config files; code written against a Beam version whose enum had different member names.

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

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

Appendix: source

Thrown at sdks/python/apache_beam/transforms/timeutil.py:50

class TimeDomain(object):
  """Time domain for streaming timers."""

  WATERMARK = 'WATERMARK'
  REAL_TIME = 'REAL_TIME'
  DEPENDENT_REAL_TIME = 'DEPENDENT_REAL_TIME'

  _RUNNER_API_MAPPING = {
      WATERMARK: beam_runner_api_pb2.TimeDomain.EVENT_TIME,
      REAL_TIME: beam_runner_api_pb2.TimeDomain.PROCESSING_TIME,
  }

  @staticmethod
  def from_string(domain):
    if domain in (TimeDomain.WATERMARK,
                  TimeDomain.REAL_TIME,
                  TimeDomain.DEPENDENT_REAL_TIME):
      return domain
    raise ValueError('Unknown time domain: %s' % domain)

  @staticmethod
  def to_runner_api(domain):
    return TimeDomain._RUNNER_API_MAPPING[domain]

  @staticmethod
  def is_event_time(domain):
    return TimeDomain.from_string(domain) == TimeDomain.WATERMARK


class TimestampCombinerImpl(metaclass=ABCMeta):
  """Implementation of TimestampCombiner."""
  @abstractmethod
  def assign_output_time(self, window, input_timestamp):
    raise NotImplementedError

  @abstractmethod
  def combine(self, output_timestamp, other_output_timestamp):

View on GitHub (pinned to 12126d8942)