apache/beam · error · TypeError

PTransform Create: Refusing to treat string as an iterable…

Error message

PTransform Create: Refusing to treat string as an iterable. (string=%r)

What it means

Raised by Create.__init__ when values is a str or bytes. Because strings are iterable character-by-character, Create would otherwise silently produce a PCollection of individual characters (or byte ints), which is almost never intended. Beam refuses outright and asks you to pass an explicit iterable of the elements you want.

Solutions

Wrap the string in a list if you want one element: beam.Create(['hello']).
Split delimited strings into a list first: beam.Create(csv_str.split(',')).
Parse JSON strings before passing: beam.Create(json.loads(s)).
For bytes content, wrap similarly: beam.Create([b'data']).

Example fix

// before
pc = p | beam.Create('hello')  # refused
// after
pc = p | beam.Create(['hello'])  # one element
# or
pc = p | beam.Create('hello'.split(','))

Defensive patterns

Strategy: type-guard

Validate before calling

assert not isinstance(values, (str, bytes)), 'Create needs an iterable of elements, wrap strings in a list'

Type guard

def is_create_input(v):
    return not isinstance(v, (str, bytes)) and hasattr(v, '__iter__')

Try / catch

try:
    pc = p | beam.Create(values)
except TypeError as e:
    log.error('Create input error: %s', e)

Prevention

Wrap strings in a list to emit them as single elements
Split or parse string config values before Create
Sanity-check the source of initial data (env vars, JSON) for bare strings

When it happens

Trigger: beam.Create('hello') or beam.Create(b'data'); passing a config value that is a string when a list was expected (e.g. a comma-separated string of items); pipeline start values read from environment variables as strings.

Common situations: Loading initial data from env vars/CLI args that arrive as strings; intending a single-element collection containing one string; JSON fields that are strings rather than arrays.

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/42e0422662a5038b. Report an issue: GitHub.

Appendix: source

Thrown at sdks/python/apache_beam/transforms/core.py:4192

        pcolls.append(pcoll.pipeline | other)
      else:
        raise TypeError(
            'FlattenWith only takes other PCollections and PTransforms, '
            f'got {other}')
    return tuple(pcolls) | Flatten()


class Create(PTransform):
  """A transform that creates a PCollection from an iterable."""
  def __init__(self, values, reshuffle=True):
    """Initializes a Create transform.

    Args:
      values: An object of values for the PCollection
    """
    super().__init__()
    if isinstance(values, (str, bytes)):
      raise TypeError(
          'PTransform Create: Refusing to treat string as '
          'an iterable. (string=%r)' % values)
    elif isinstance(values, dict):
      values = values.items()
    self.values = tuple(values)
    self.reshuffle = reshuffle
    self._coder = typecoders.registry.get_coder(self.get_output_type())

  def __getstate__(self):
    serialized_values = [self._coder.encode(v) for v in self.values]
    return serialized_values, self.reshuffle, self._coder

  def __setstate__(self, state):
    serialized_values, self.reshuffle, self._coder = state
    self.values = [self._coder.decode(v) for v in serialized_values]

  def to_runner_api_parameter(self, context):
    # type: (PipelineContext) -> typing.Tuple[str, bytes]

View on GitHub (pinned to 12126d8942)