apache/beam · warning

%name%

Error message

%name%

What it means

emit_warning is the generic deprecation/experimental notice emitter in apache_beam.utils.annotations. For an annotation labeled 'deprecated' it emits BeamDeprecationWarning, otherwise FutureWarning, replacing the %name% placeholder in the annotation's message template with the actual function name, at stacklevel=3 to point at the caller.

Solutions

  1. Read the warning to identify the deprecated function and switch to the 'current' replacement named in the annotation (the annotate decorator documents it).
  2. Check the Beam migration guide for the deprecated API's successor and update call sites.
  3. If migration must be deferred, suppress selectively: warnings.filterwarnings('ignore', category=BeamDeprecationWarning).
  4. Pin the current Beam version temporarily if you cannot migrate yet (deprecated APIs are eventually removed).

Example fix

// before
beam.FlatMapTuple(lambda kv: [kv])  # deprecated helper
// after
beam.FlatMap(lambda kv: [kv])
Defensive patterns

Strategy: try-catch

Validate before calling

# Detect deprecated API usage in CI
python -W error::FutureWarning your_pipeline.py

Try / catch

import warnings
from apache_beam.utils.annotations import BeamDeprecationWarning
with warnings.catch_warnings():
    warnings.filterwarnings('ignore', category=BeamDeprecationWarning)
    legacy_call()

Prevention

When it happens

Trigger: Calling any Beam API decorated with @annotate('deprecated', ...) or @annotate('experimental', ...) — e.g. older Map/FlatMap-style helpers — triggers this warning with the decorated function's name substituted for %name%.

Common situations: Upgrading Beam versions: code written against an API deprecated in a prior release still works but now warns; CI logs fill with BeamDeprecationWarning/FutureWarning.

Understand the failure class

Background: "is deprecated and will be removed" — deprecation warnings for old API names, keywords, and options, and how to migrate before the removal release — this error's family across 29 libraries.

Related errors

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

Appendix: source

Thrown at sdks/python/apache_beam/utils/annotations.py:120

    else:
      if label == 'deprecated' and '%since%' not in custom_message:
        raise TypeError(
            "Replacement string %since% not found on \
        custom message")
      emptyArg = lambda x: '' if x is None else x
      message = custom_message\
      .replace('%since%', emptyArg(since))\
      .replace('%current%', emptyArg(current))\
      .replace('%extra%', emptyArg(extra_message))
    self.label = label
    self.message = message

  def emit_warning(self, fnc_name):
    if self.label == 'deprecated':
      warning_type = BeamDeprecationWarning
    else:
      warning_type = FutureWarning
    warnings.warn(
        self.message.replace('%name%', fnc_name), warning_type, stacklevel=3)


def annotate(label, since, current, extra_message, custom_message=None):
  """Decorates an API with a deprecated or experimental annotation.

  Args:
    label: the kind of annotation ('deprecated' or 'experimental').
    since: the version that causes the annotation.
    current: the suggested replacement function.
    extra_message: an optional additional message.
    custom_message: if the default message does not suffice, the message
      can be changed using this argument. A string
      whit replacement tokens.
      A replecement string is were the previus args will
      be located on the custom message.
      The following replacement strings can be used:
      %name% -> API.__name__

View on GitHub (pinned to 12126d8942)