apache/beam · error · ValueError

The given pcoll %s is not a dict, an iterable or a PCollecti

Error message

The given pcoll %s is not a dict, an iterable or a PCollection.

What it means

ib.show() flattens whatever you pass into a list of PCollections/deferred DataFrames. Each element must be a dict, an iterable of PCollections, a PCollection, or a DeferredBase (deferred DataFrame/Series). If an element is none of those, iter() raises TypeError and the code converts it to a ValueError telling you the given pcoll is not a dict, an iterable or a PCollection. It fails fast on wrong arguments before any pipeline work starts.

Source

Thrown at sdks/python/apache_beam/runners/interactive/interactive_beam.py:758

      # This is equivalent to `show(square)` because `square` depends on `init`
      # and `init` is included in the pipeline fragment and computed anyway.
      show(init, square)

      # Below is similar to running `p.run()`. It computes data for both
      # PCollection `square` and PCollection `cube`, then visualizes them.
      show(square, cube)
  """
  flatten_pcolls = []
  for pcoll_container in pcolls:
    if isinstance(pcoll_container, dict):
      flatten_pcolls.extend(pcoll_container.values())
    elif isinstance(pcoll_container, (beam.pvalue.PCollection, DeferredBase)):
      flatten_pcolls.append(pcoll_container)
    else:
      try:
        flatten_pcolls.extend(iter(pcoll_container))
      except TypeError:
        raise ValueError(
            'The given pcoll %s is not a dict, an iterable or a PCollection.' %
            pcoll_container)

  # Iterate through the given PCollections and convert any deferred DataFrames
  # or Series into PCollections.
  pcolls = set()

  # The element type is used to help visualize the given PCollection. For the
  # deferred DataFrame/Series case it is the proxy of the frame.
  element_types = {}
  for pcoll in flatten_pcolls:
    if isinstance(pcoll, DeferredBase):
      pcoll, element_type = deferred_df_to_pcollection(pcoll)
      watch({'anonymous_pcollection_{}'.format(id(pcoll)): pcoll})
    else:
      element_type = pcoll.element_type

    element_types[pcoll] = element_type

View on GitHub (pinned to 12126d8942)

Solutions

1. Pass actual PCollection objects produced by your beam pipeline, not derived handles or results.
2. If passing a container, make sure every element is a PCollection or a deferred DataFrame/Series.
3. Remove literal/constant values — wrap them in a PCollection first (beam.Create([...])) then show that.
4. Check for None: if the pcoll variable is None because a transform returned nothing upstream, fix the upstream branch first.
5. For pandas DataFrames, use apache_beam.dataframes to get a deferred beam DataFrame rather than passing the raw pandas object.

Example fix

// before: ib.show(result)  # result is a PipelineResult | // after: pcoll = pipeline | 'Create' >> beam.Create([1, 2, 3]); ib.show(pcoll)

import apache_beam as beam; from apache_beam.dataframes import DeferredBase; def is_pcoll_like(x): return isinstance(x, (beam.pvalue.PCollection, DeferredBase)); assert all(is_pcoll_like(a) for a in show_args)

def is_pcoll_like(x): import apache_beam as beam; from apache_beam.dataframes import DeferredBase; return isinstance(x, (beam.pvalue.PCollection, DeferredBase))

try: ib.show(*pcolls) | except ValueError as e: print('show() got a non-PCollection argument:', e); print([type(p) for p in pcolls])  # re-inspect inputs

When it happens

Trigger: ib.show(42) or ib.show(None) or ib.show(pipeline_result) where the argument has no __iter__ and is not a PCollection/DeferredBase; a list containing a non-PCollection element such as a PipelineResult, a literal value, or a raw pandas DataFrame (not a beam deferred DataFrame).

Common situations: Notebooks: passing the output of a non-interactive pipeline run into ib.show; lists mixing PTransform outputs with literal values; passing a pipeline variable name that was later reassigned to a scalar; passing numpy arrays or tensors.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• The given pcoll {pcoll_container} is not a dict, an iterable
• {pcoll} is not an apache_beam.pvalue.PCollection.
• All PCollections must belong to the same pipeline.
• The beam_sql magic tries to query PCollections from multiple
• cache_root GCS bucket path is invalid.

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