apache/beam · error · ValueError

Class name must not be empty

Error message

Class name must not be empty

What it means

Validation guard in JavaClassLookupPayloadBuilder.__init__: this builder constructs a payload that directly instantiates a Java transform by its fully qualified class name, and an empty/None class_name would produce an invalid expansion request that would only fail later on the expansion service. It fires when callers pass an empty string (e.g., from a blank configuration value or an unset identifier) instead of a real class name.

Solutions

1. Pass the fully qualified Java class name, e.g. 'com.example.MyTransform'.
2. Validate the class_name string is non-empty before constructing the builder.
3. Fix the config/env source that yielded an empty value.

Example fix

# before
builder = JavaClassLookupPayloadBuilder(config.get('class', ''))
# after
class_name = config.get('class')
if not class_name:
  raise ValueError('Java transform class name is required')
builder = JavaClassLookupPayloadBuilder(class_name)

if not class_name:
    raise ValueError('Java transform class name is required')
JavaClassLookupPayloadBuilder(class_name)

def is_valid_class_name(name) -> bool:
    return isinstance(name, str) and bool(name.strip()) and '.' in name

try:
    builder = JavaClassLookupPayloadBuilder(class_name)
except ValueError:
    raise ValueError('fully qualified Java class name required, got %r' % class_name)

When it happens

Trigger: Constructing the builder with JavaClassLookupPayloadBuilder('') or with a class_name variable that resolved to an empty string.

Common situations: Class names read from config files or environment variables that are unset/empty; failed string parsing of a fully qualified name.

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

• BigQueryIO.Write transforms cannot be converted to a…
• Cannot create from non-Java
• cannot register component
• Constructor or constructor method can only be specified once
• Could not find coder for URN " + urn

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

Appendix: source

Thrown at sdks/python/apache_beam/transforms/external.py:299

        configuration_schema=self._schema_proto,
        configuration_row=RowCoder(self._schema_proto).encode(
            dict_to_row(self._schema_proto, self._kwargs)))


class JavaClassLookupPayloadBuilder(PayloadBuilder):
  """
  Builds a payload for directly instantiating a Java transform using a
  constructor and builder methods.
  """

  IGNORED_ARG_FORMAT = 'ignore%d'

  def __init__(self, class_name):
    """
    :param class_name: fully qualified name of the transform class.
    """
    if not class_name:
      raise ValueError('Class name must not be empty')

    self._class_name = class_name
    self._constructor_method = None
    self._constructor_param_args = None
    self._constructor_param_kwargs = None
    self._builder_methods_and_params = OrderedDict()

  def _args_to_named_fields(self, args):
    next_field_id = 0
    named_fields = OrderedDict()
    for value in args:
      if value is None:
        raise ValueError(
            'Received value None. None values are currently not supported')
      named_fields[(
          JavaClassLookupPayloadBuilder.IGNORED_ARG_FORMAT %
          next_field_id)] = value
      next_field_id += 1

View on GitHub (pinned to 12126d8942)