apache/beam · error · ValueError

Invalid DisplayDataItem

Error message

Invalid DisplayDataItem %s. Key must not be None.

What it means

DisplayDataItem.is_valid validates that an item carries a key; it raises ValueError when the item's key attribute is None. Every display data item must have a key to be labeled in the runner API proto.

Solutions

  1. Set a key when creating the item: DisplayData.create_from or provide a non-None key field.
  2. Inspect the offending item (printed in the message) to find where the key was lost.
  3. Avoid manual DisplayDataItem construction; derive items from display_data() dictionaries.

Example fix

// before
item = DisplayDataItem(value=42)  # no key
// after
item = DisplayDataItem(key='my_value', value=42)
Defensive patterns

Strategy: validation

Validate before calling

for item in display_data.items:
    if getattr(item, 'key', None) is None:
        raise ValueError('display data item missing key')

Type guard

def item_has_key(item) -> bool:
    return getattr(item, 'key', None) is not None

Try / catch

try:
    d = display_data.get_dict()
except ValueError as e:
    if 'Key must not be None' in str(e):
        skip_or_fix_invalid_items(display_data)
        d = display_data.get_dict()
    else:
        raise

Prevention

When it happens

Trigger: Building/serializing a DisplayDataItem where the key was never set (e.g. DisplayData created from items dict where key metadata is missing) and get_dict()/is_valid() is invoked.

Common situations: Manually constructing DisplayDataItem without a key; programmatic DisplayData manipulation dropping the key field; buggy custom display_data implementations.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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

Appendix: source

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

    if self._drop_if_none and self.value is None:
      return True
    if self._drop_if_default and self.value == self._default:
      return True
    return False

  def is_valid(self):
    # type: () -> None

    """ Checks that all the necessary fields of the :class:`DisplayDataItem`
    are filled in. It checks that neither key, namespace, value or type are
    :data:`None`.

    Raises:
      ValueError: If the item does not have a key, namespace,
        value or type.
    """
    if self.key is None:
      raise ValueError(
          'Invalid DisplayDataItem %s. Key must not be None.' % self)
    if self.namespace is None:
      raise ValueError(
          'Invalid DisplayDataItem %s. Namespace must not be None' % self)
    if self.value is None:
      raise ValueError(
          'Invalid DisplayDataItem %s. Value must not be None' % self)
    if self.type is None:
      raise ValueError(
          'Invalid DisplayDataItem. Value {} is of an unsupported type.'.format(
              self.value))

  def _get_dict(self):
    res = {
        'key': self.key,
        'namespace': self.namespace,
        'type': self.type if self.type != 'CLASS' else 'STRING'
    }

View on GitHub (pinned to 12126d8942)