apache/beam · error · TypeError

Attempting to create a TaggedOutput with non-string tag %s

Error message

Attempting to create a TaggedOutput with non-string tag %s

What it means

TaggedOutput.__init__ is a type guard on the tag argument: tagged outputs are keyed by string tags in ParDo/Map, so a non-string tag (int, tuple, etc.) would break output dispatch and is rejected at construction.

Source

Thrown at sdks/python/apache_beam/pvalue.py:341

    self._pcolls[tag] = pcoll
    return pcoll


TagType = TypeVar('TagType', bound=str)
ValueType = TypeVar('ValueType')


class TaggedOutput(Generic[TagType, ValueType]):
  """An object representing a tagged value.

  ParDo, Map, and FlatMap transforms can emit values on multiple outputs which
  are distinguished by string tags. The DoFn will return plain values
  if it wants to emit on the main output and TaggedOutput objects
  if it wants to emit a value on a specific tagged output.
  """
  def __init__(self, tag: TagType, value: ValueType) -> None:
    if not isinstance(tag, str):
      raise TypeError(
          'Attempting to create a TaggedOutput with non-string tag %s' %
          (tag, ))
    self.tag = tag
    self.value = value


class AsSideInput(object):
  """Marker specifying that a PCollection will be used as a side input.

  When a PCollection is supplied as a side input to a PTransform, it is
  necessary to indicate how the PCollection should be made available
  as a PTransform side argument (e.g. in the form of an iterable, mapping,
  or single value).  This class is the superclass of all the various
  options, and should not be instantiated directly. (See instead AsSingleton,
  AsIter, etc.)
  """
  def __init__(self, pcoll: PCollection) -> None:
    from apache_beam.transforms import sideinputs

View on GitHub (pinned to 12126d8942)

Solutions

Convert the tag with str(tag) before constructing TaggedOutput
Use consistent string constants for side-output tags
Apply the tag via beam.pvalue.TaggedOutput(str(tag), value) or beam.tag_output(str(tag), value)

Example fix

// before
yield beam.pvalue.TaggedOutput(0, element)
// after
yield beam.pvalue.TaggedOutput('even', element)

Defensive patterns

Strategy: validation

Validate before calling

if not isinstance(tag, str):
    raise ValueError('Side-output tag must be a string')

Type guard

def is_valid_tag(tag):
    return isinstance(tag, str)

Try / catch

try:
    out = beam.pvalue.TaggedOutput(tag, value)
except TypeError as e:
    out = beam.pvalue.TaggedOutput(str(tag), value)

Prevention

Coerce numeric tags with str() before creating TaggedOutput
Avoid enum/int constants for side-output tags
Add a lint/test asserting all tags emitted by DoFns are strings

When it happens

Trigger: Returning beam.TaggedOutput(1, value) from a DoFn; using an enum or int constant as a tag; passing a None tag.

Common situations: DoFns emitting side outputs with numeric channel ids converted from other systems; refactors replacing string tags with enum values.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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