apache/beam · error · ValueError

Element of class . does not subclass PipelineOptions

Error message

Element of class {}.{} does not subclass PipelineOptions

What it means

DisplayData.create_from_options requires its argument to be an instance of PipelineOptions. It raises ValueError when an object of another class is passed, naming the offending module and class in the message.

Solutions

Construct PipelineOptions first: DisplayData.create_from_options(PipelineOptions(argv)).
Ensure the object passed is an instance of a PipelineOptions subclass, not the class object.
If the object is a HasDisplayData (e.g. a DoFn/transform), call DisplayData.create_from() instead.

Example fix

// before
dd = DisplayData.create_from_options(PipelineOptions)
// after
dd = DisplayData.create_from_options(PipelineOptions(['--runner=DirectRunner']))

Defensive patterns

Strategy: type-guard

Validate before calling

from apache_beam.options.pipeline_options import PipelineOptions
assert isinstance(opts, PipelineOptions), 'create_from_options needs a PipelineOptions instance'

Type guard

def is_pipeline_options(o) -> bool:
    from apache_beam.options.pipeline_options import PipelineOptions
    return isinstance(o, PipelineOptions)

Try / catch

try:
    dd = DisplayData.create_from_options(opts)
except ValueError as e:
    if 'does not subclass PipelineOptions' in str(e):
        dd = DisplayData.create_from_options(PipelineOptions([]))
    else:
        raise

Prevention

Instantiate PipelineOptions before passing it
Use create_from for HasDisplayData objects and create_from_options for options
Check argument types in runner/tooling wrappers

When it happens

Trigger: Calling DisplayData.create_from_options(opts) where opts is a plain dict, a custom config class, or a PipelineOptions subclass instance but the function receives the class itself (not an instance).

Common situations: Passing the PipelineOptions class instead of an instance; passing raw dict-based options from custom runner code; mixing up create_from_options and create_from.

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

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

Appendix: source

Thrown at sdks/python/apache_beam/transforms/display.py:218

    :class:`~apache_beam.options.pipeline_options.PipelineOptions` instance.

    When creating :class:`~apache_beam.transforms.display.DisplayData`, this
    method will convert the value of any item of a non-supported type to its
    string representation.
    The normal :meth:`.create_from()` method rejects those items.

    Returns:
      ~apache_beam.transforms.display.DisplayData:
        A :class:`~apache_beam.transforms.display.DisplayData` instance with
        populated items.

    Raises:
      ValueError: If the **has_display_data** argument is
        not an instance of :class:`HasDisplayData`.
    """
    from apache_beam.options.pipeline_options import PipelineOptions
    if not isinstance(pipeline_options, PipelineOptions):
      raise ValueError(
          'Element of class {}.{} does not subclass PipelineOptions'.format(
              pipeline_options.__module__, pipeline_options.__class__.__name__))

    items = {
        k: (v if DisplayDataItem._get_value_type(v) is not None else str(v))
        for k, v in pipeline_options.display_data().items()
    }
    return cls(pipeline_options._get_display_data_namespace(), items)

  @classmethod
  def create_from(cls, has_display_data, extra_items=None):
    """ Creates :class:`~apache_beam.transforms.display.DisplayData` from a
    :class:`HasDisplayData` instance.

    Returns:
      ~apache_beam.transforms.display.DisplayData:
        A :class:`~apache_beam.transforms.display.DisplayData` instance with
        populated items.

View on GitHub (pinned to 12126d8942)