apache/beam · error · ValueError

Unknown access pattern: '%s'

Error message

Unknown access pattern: '%s'

What it means

When materializing a side input for a given window, the runner maps the declared access pattern (URN) to a view type. If the access pattern is neither ITERABLE, MULTISET, nor the supported MULTIMAP case, it raises 'Unknown access pattern'. The declared side-input view kind is not one this Beam version can build.

Source

Thrown at sdks/python/apache_beam/runners/worker/bundle_processor.py:495

            if key not in cache:
              keyed_state_key = beam_fn_api_pb2.StateKey()
              keyed_state_key.CopyFrom(state_key)
              keyed_state_key.multimap_side_input.key = (
                  key_coder_impl.encode_nested(key))
              cache[key] = _StateBackedIterable(
                  state_handler, keyed_state_key, value_coder)

            return cache[key]

          def __reduce__(self):
            # TODO(robertwb): Figure out how to support this.
            raise TypeError(common_urns.side_inputs.MULTIMAP.urn)

        raw_view = MultiMap()

      else:
        raise ValueError("Unknown access pattern: '%s'" % access_pattern)

      self._cache[target_window] = self._side_input_data.view_fn(raw_view)
    return self._cache[target_window]

  def is_globally_windowed(self) -> bool:
    return (
        self._side_input_data.window_mapping_fn ==
        sideinputs._global_window_mapping_fn)

  def reset(self) -> None:
    # TODO(BEAM-5428): Cross-bundle caching respecting cache tokens.
    self._cache = {}


class ReadModifyWriteRuntimeState(userstate.ReadModifyWriteRuntimeState):
  def __init__(self, underlying_bag_state):
    self._underlying_bag_state = underlying_bag_state

View on GitHub (pinned to 12126d8942)

Solutions

  1. Upgrade apache_beam on both submission and worker sides so the URN is supported
  2. Change the side input to a supported view type (AsIter, AsDict with standard keys)
  3. Avoid cross-language side inputs with unsupported access patterns; materialize via a regular PCollection + join instead
  4. Inspect the access_pattern URN in the pipeline proto to confirm which pattern is declared

Example fix

// before
side = beam.pvalue.AsMultiMap(pcoll)  # unsupported pattern in this version
// after
side = beam.pvalue.AsDict(pcoll)  # standard supported access pattern
Defensive patterns

Strategy: validation

Validate before calling

SUPPORTED_VIEW_URNS = {'beam:side_input:iterable', 'beam:side_input:multiset', 'beam:side_input:multimap'}
def side_input_supported(pipeline_proto):
    for t in pipeline_proto.components.transforms.values():
        for inp in t.inputs.values():
            # inspect declared access patterns when expanding portable pipelines
            pass
    return True  # verify URNs during expansion service output

Try / catch

try:
    side = beam.pvalue.AsMultiMap(pcoll)
    result = (pcoll2 | beam.Map(lambda x, s: x, s=side))
except (ValueError, TypeError) as e:
    if 'Unknown access pattern' in str(e) or 'MULTIMAP' in str(e):
        logging.warning('Unsupported side input view; falling back to AsDict')
        side = beam.pvalue.AsDict(pcoll)
    else:
        raise

Prevention

When it happens

Trigger: A PTransform declares a side input with an access_pattern URN that SideInputData/RemoteSideInputMapImpl.get doesn't recognize (bundle_processor.py:495), e.g. an exotic or newer view URN from a different SDK version.

Common situations: Cross-language/portable pipelines where the producing SDK declares view types the Python worker can't materialize; using beam.pvalue.AsDict/AsSingleton variants over unsupported multi-map patterns; version mismatch between harness and pipeline construction.

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

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