apache/beam · error · ValueError

Unsupported access pattern for %r: %r

Error message

Unsupported access pattern for %r: %r

What it means

During pipeline translation, the DataflowRunner converts each side input into a representation Dataflow supports. If a ParDo accesses a side input with an access pattern (iteration order / windowing view) that Dataflow's non-portable path cannot represent, this ValueError is thrown naming the transform label and the unsupported pattern.

Source

Thrown at sdks/python/apache_beam/runners/dataflow/dataflow_runner.py:285

            access_pattern = side_input._side_input_data().access_pattern
            if access_pattern == common_urns.side_inputs.ITERABLE.urn:
              # TODO(https://github.com/apache/beam/issues/20043): Stop
              # patching up the access pattern to appease Dataflow when
              # using the UW and hardcode the output type to be Any since
              # the Dataflow JSON and pipeline proto can differ in coders
              # which leads to encoding/decoding issues within the runner.
              side_input.pvalue.element_type = typehints.Any
              new_side_input = _DataflowIterableSideInput(side_input)
            elif access_pattern == common_urns.side_inputs.MULTIMAP.urn:
              # Ensure the input coder is a KV coder and patch up the
              # access pattern to appease Dataflow.
              side_input.pvalue.element_type = typehints.coerce_to_kv_type(
                  side_input.pvalue.element_type, transform_node.full_label)
              side_input.pvalue.requires_deterministic_key_coder = (
                  deterministic_key_coders and transform_node.full_label)
              new_side_input = _DataflowMultimapSideInput(side_input)
            else:
              raise ValueError(
                  'Unsupported access pattern for %r: %r' %
                  (transform_node.full_label, access_pattern))
            new_side_inputs.append(new_side_input)
          transform_node.side_inputs = new_side_inputs
          transform_node.transform.side_inputs = new_side_inputs

    return SideInputVisitor()

  @staticmethod
  def flatten_input_visitor():
    # Imported here to avoid circular dependencies.
    from apache_beam.pipeline import PipelineVisitor

    class FlattenInputVisitor(PipelineVisitor):
      """A visitor that replaces the element type for input ``PCollections``s of
       a ``Flatten`` transform with that of the output ``PCollection``.
      """
      def visit_transform(self, transform_node):

View on GitHub (pinned to 12126d8942)

Solutions

1. Use a standard side-input view: pvalue.AsDict(x) or pvalue.AsList(x) instead of the unsupported pattern.
2. Simplify side-input windowing (e.g. re-window to the global window or use beam.pvalue.AsSingleton with a default).
3. Upgrade apache-beam — newer versions support more side-input access patterns on Dataflow.
4. Restructure the pipeline to join via CoGroupByKey instead of an exotic side-input view.

Example fix

// before
filtered = numbers | 'Filter' >> beam.ParDo(FilterFn(), min_v=beam.pvalue.AsIter(small))
// after
filtered = numbers | 'Filter' >> beam.ParDo(FilterFn(), min_v=beam.pvalue.AsSingleton(small, default=0))

def uses_supported_side_inputs(pipeline):
    # avoid AsIter/AsMultimap on windowed side inputs; prefer AsDict/AsSingleton
    for t in pipeline.applied_transforms:
        if 'AsMultimap' in str(t.transform): return False
    return True

try:
    with beam.Pipeline(runner='DataflowRunner', options=opts) as p:
        build(p)
except ValueError as e:
    if 'Unsupported access pattern' in str(e):
        # fall back to CoGroupByKey-based join
        build_with_cogroupbykey()

When it happens

Trigger: Calling pvalue.AsIter/AsList/AsMultimap (or beam.SideInput access) with a windowing/view combination the runner rejects during DataflowRunner.visit_transform — specifically an access_pattern that is neither MATERIALIZE_ITERABLE nor the multimap form.

Common situations: Using AsMultimap with windowed side inputs, using unsupported side-input views on non-global windows, or piping code written for a newer Beam version to an older Dataflow runner.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Unknown access_pattern: %s
• Value for sideinput %s not provided
• Could not find element
• Too many matches
• Could not translate the internal step name %r since job grap

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