apache/beam · error · ValueError

Label does not exist for Lineage

Error message

Label {} does not exist for Lineage

What it means

Lineage.query() only accepts labels registered in Lineage._METRICS (the known lineage metric names). Passing an unknown label raises ValueError; note the message also uses comma-style formatting ('ValueError("Label {} ...", label)') so the label placeholder is not substituted.

Solutions

1. Use one of the labels defined in Lineage._METRICS (check the Lineage class in apache_beam/metrics/metric.py).
2. Inspect Lineage._METRICS at runtime to enumerate valid labels before querying.
3. Upgrade Beam if the label you need was added in a newer version.

Example fix

- Lineage.query(results, 'source')
+ from apache_beam.metrics.metric import Lineage
+ assert 'SOURCE_CODE_BRANCH' in Lineage._METRICS
+ Lineage.query(results, 'SOURCE_CODE_BRANCH')

from apache_beam.metrics.metric import Lineage
assert label in Lineage._METRICS, f'valid labels: {Lineage._METRICS}'

def is_lineage_label(label):
    from apache_beam.metrics.metric import Lineage
    return label in Lineage._METRICS

try:
    out = Lineage.query(results, label)
except ValueError:
    logger.error('unknown lineage label %r, valid: %s', label, Lineage._METRICS)

When it happens

Trigger: Calling Lineage.query(results, 'source_code_branch') with a label not among Lineage's supported lineage metrics (e.g. SOURCE_CODE_BRANCH, SOURCE_CODE_REVISION, or a typo of one).

Common situations: Custom lineage/observability queries guessing label names; renamed or newly added lineage labels not present in the installed Beam version.

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

• A BigQuery table or a query must be specified
• A cluster_identifier should be Optional[Union[str…
• A context manager constructor (not a fully constructed…
• A has been supplied to the model handler, but the required…
• A pubsub message attribute key must not exceed 256 bytes.

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

Appendix: source

Thrown at sdks/python/apache_beam/metrics/metric.py:515

            *segments,
            subtype=subtype,
            last_segment_sep=last_segment_sep))

  def add_raw(self, *rollup_segments: str) -> None:
    """Adds the given fqn as lineage.

    `rollup_segments` should be an iterable of strings whose concatenation
    is a valid Dataplex FQN.  In particular, this means they will often have
    trailing delimiters.
    """
    self.metric.add(rollup_segments)

  @staticmethod
  def query(results: MetricResults,
            label: str,
            truncated_marker: str = '*') -> set[str]:
    if not label in Lineage._METRICS:
      raise ValueError("Label {} does not exist for Lineage", label)
    response = results.query(
        MetricsFilter().with_namespace(Lineage.LINEAGE_NAMESPACE).with_name(
            label))[MetricResults.BOUNDED_TRIES]
    result = set()
    for metric in response:
      for fqn in metric.committed.flattened():
        result.add(''.join(fqn[:-1]) + (truncated_marker if fqn[-1] else ''))
      for fqn in metric.attempted.flattened():
        result.add(''.join(fqn[:-1]) + (truncated_marker if fqn[-1] else ''))
    return result

View on GitHub (pinned to 12126d8942)