What causes "Metric name must be non-empty" in apache/beam?

Pass a non-empty metric name string, e.g. Metrics.counter('MyDoFn', 'elements_read').

apache/beam · error · ValueError

Metric name must be non-empty

Error message

Metric name must be non-empty

What it means

Metric.__init__ raises ValueError when no MonitoringInfo URN is given and the metric name is empty. Beam requires namespace+name to uniquely identify a user metric when no urn is provided, so an empty name makes the metric unidentifiable. The check runs only when urn is falsy.

Source

Thrown at sdks/python/apache_beam/metrics/metricbase.py:80

      urn: Optional[str] = None,
      labels: Optional[dict[str, str]] = None) -> None:
    """Initializes ``MetricName``.

    Note: namespace and name should be set for user metrics,
    urn and labels should be set for an arbitrary metric to package into a
    MonitoringInfo.

    Args:
      namespace: A string with the namespace of a metric.
      name: A string with the name of a metric.
      urn: URN to populate on a MonitoringInfo, when sending to RunnerHarness.
      labels: Labels to populate on a MonitoringInfo
    """
    if not urn:
      if not namespace:
        raise ValueError('Metric namespace must be non-empty')
      if not name:
        raise ValueError('Metric name must be non-empty')
    self.namespace = namespace
    self.name = name
    self.urn = urn
    self.labels = labels if labels else {}

  def __eq__(self, other):
    return (
        self.namespace == other.namespace and self.name == other.name and
        self.urn == other.urn and self.labels == other.labels)

  def __str__(self):
    if self.urn:
      return 'MetricName(namespace={}, name={}, urn={}, labels={})'.format(
          self.namespace, self.name, self.urn, self.labels)
    else:  # User counter case.
      return 'MetricName(namespace={}, name={})'.format(
          self.namespace, self.name)

View on GitHub (pinned to 12126d8942)

Solutions

Pass a non-empty metric name string, e.g. Metrics.counter('MyDoFn', 'elements_read').
Supply a urn argument instead; with a urn set, name/namespace validation is skipped.
Validate the name before constructing the metric and raise a clearer app-level error.

Example fix

// before
_read = Metrics.counter('MyDoFn', metric_name)  # metric_name == ''
// after
assert metric_name, 'metric name required'
_read = Metrics.counter('MyDoFn', metric_name or 'elements_read')

Defensive patterns

Strategy: validation

Validate before calling

if not urn and not name:
    raise ValueError('metric name required when urn is not set')
metric = Metrics.counter(namespace, name)

Try / catch

try:
    metric = Metrics.counter(namespace, name)
except ValueError:
    logger.exception('invalid metric name %r', name)
    raise

Prevention

Use literal string names for metrics instead of dynamically computed ones where possible.
Validate names built from f-strings/config before constructing metrics.

When it happens

Trigger: Calling Metrics.counter/counter distribution/gauge (or Metric directly) with name='' or None and no urn, e.g. Metrics.counter('MyDoFn', '') or name pulled from an empty variable.

Common situations: Metric names built from f-strings or config values that resolve to empty; refactoring where the literal name was accidentally removed; constructing metrics in a loop over a list containing empty strings.

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/43dbd9ff1a71422f. Report an issue: GitHub.