apache/beam · error · ValueError

Unknown access_pattern: %s

Error message

Unknown access_pattern: %s

What it means

AsSideInput._from_runtime_iterable materializes a runtime iterable into the in-memory representation matching the side input's declared access pattern (SINGLETON or MULTIMAP). The library throws this ValueError when the access_pattern URN is neither, meaning the view options were constructed with an unrecognized or corrupted access pattern.

Source

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

    return False


class _UnpickledSideInput(AsSideInput):
  def __init__(self, side_input_data: 'SideInputData') -> None:
    self._data = side_input_data
    self._window_mapping_fn = side_input_data.window_mapping_fn

  @staticmethod
  def _from_runtime_iterable(it, options):
    access_pattern = options['data'].access_pattern
    if access_pattern == common_urns.side_inputs.ITERABLE.urn:
      raw_view = it
    elif access_pattern == common_urns.side_inputs.MULTIMAP.urn:
      raw_view = collections.defaultdict(list)
      for k, v in it:
        raw_view[k].append(v)
    else:
      raise ValueError('Unknown access_pattern: %s' % access_pattern)
    return options['data'].view_fn(raw_view)

  def _view_options(self):
    return {
        'data': self._data,  # For non-fn-api runners.
        'window_mapping_fn': self._data.window_mapping_fn,
        'coder': self._windowed_coder(),
    }

  def _side_input_data(self):
    return self._data


class SideInputData(object):
  """All of the data about a side input except for the bound PCollection."""
  def __init__(
      self,
      access_pattern: str,

View on GitHub (pinned to 12126d8942)

Solutions

1. Use only the provided side-input wrappers (AsSingleton, AsIter, AsDict, AsMultimap) instead of constructing AsSideInput/view options manually
2. Verify the access_pattern urn string exactly matches apache_beam.portability.common_urns.side_inputs.SINGLETON.urn or MULTIMAP.urn
3. Upgrade/downgrade the Python SDK so runner and SDK agree on side-input URNs
4. Check any custom ViewFn/Windowing for a copy-paste error in the urn it declares

Example fix

// before
AsSideInput(pcoll, access_pattern='MULTIMAP ')  # trailing space
// after
from apache_beam.portability import common_urns
AsSideInput(pcoll, access_pattern=common_urns.side_inputs.MULTIMAP.urn)

from apache_beam.portability import common_urns
assert access_pattern in (common_urns.side_inputs.SINGLETON.urn, common_urns.side_inputs.MULTIMAP.urn), access_pattern

def is_valid_access_pattern(urn): return urn in (common_urns.side_inputs.SINGLETON.urn, common_urns.side_inputs.MULTIMAP.urn)

When it happens

Trigger: Calling beam.pvalue.AsSideInput / AsMultimap / AsSingleton on a PCollection whose access_pattern urn is not common_urns.side_inputs.SINGLETON or MULTIMAP — e.g. a custom ViewFn passing a wrong urn, or runner-injected options with a typo'd/unsupported urn.

Common situations: Custom runner or custom view implementation supplying its own access_pattern; Beam version mismatch where a runner emits a side-input urn the Python SDK doesn't recognize; hand-built view_options in tests.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Value for sideinput %s not provided
• Unsupported access pattern for %r: %r
• Unknown access pattern: '%s'
• Can only iterate once over PrefetchingSourceSetIterable inst
• PCollection used directly as side input argument. Specify As

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