apache/beam · error · ValueError

Unknown language for

Error message

Unknown language {language} for {identify_object(spec)}

What it means

When preprocess_languages rewrites a language-sensitive transform to type-<language>, an explicitly set language that has no corresponding known transform/provider produces this ValueError. Unlike the 'generic' case, the user did specify a language — it is just not available in this environment.

Solutions

  1. Correct the language string (check supported values: typically 'python', 'java', 'generic').
  2. Register the provider for that language's transform variant.
  3. Switch to a supported language for this transform or run in an environment that provides it.

Example fix

# before
config:
  language: javascript
# after
config:
  language: python
Defensive patterns

Strategy: validation

Validate before calling

SUPPORTED_LANGS = {'generic', 'python', 'java'}
for t in spec.get('transforms', []):
    lang = t.get('config', {}).get('language')
    if lang is not None and lang not in SUPPORTED_LANGS:
        raise ValueError(f"unsupported language {lang} for {t.get('name')}")

Type guard

def lang_supported(t, known):
    lang = t.get('config', {}).get('language', 'generic')
    return f"{t['type']}-{lang}" in known

Try / catch

try:
    spec = expand_pipeline(spec, providers=providers)
except ValueError as e:
    if 'Unknown language' in str(e):
        raise SystemExit(f"{e} — use a supported language or register its provider")
    raise

Prevention

When it happens

Trigger: preprocess_languages on a spec whose config.language is set to a non-'generic' value (e.g. 'javascript', 'rust') where known_transforms is non-empty and '<type>-<language>' is not in known_transforms — the language's provider is not registered or the language is unsupported for that transform.

Common situations: Requesting a language the runner/plugins don't support (e.g. javascript on a setup with only python providers); typo in the language string; Beam version that doesn't ship that language's transform implementation.

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

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

Appendix: source

Thrown at sdks/python/apache_beam/yaml/yaml_transform.py:1348

      if spec['type'] not in known_transforms:
        raise ValueError(
            'Unknown type or missing provider '
            f'for type {spec["type"]} for {identify_object(spec)}')
    return spec

  def preprocess_languages(spec):
    if spec['type'] in ('AssignTimestamps',
                        'Combine',
                        'Filter',
                        'MapToFields',
                        'Partition'):
      language = spec.get('config', {}).get('language', 'generic')
      new_type = spec['type'] + '-' + language
      if known_transforms and new_type not in known_transforms:
        if language == 'generic':
          raise ValueError(f'Missing language for {identify_object(spec)}')
        else:
          raise ValueError(
              f'Unknown language {language} for {identify_object(spec)}')
      return dict(spec, type=new_type, name=spec.get('name', spec['type']))
    else:
      return spec

  def validate_transform_references(spec):
    name = spec.get('name', '')
    transform_type = spec.get('type')
    inputs = spec.get('input').get('input', [])

    if not is_empty(inputs):
      input_values = [inputs] if isinstance(inputs, str) else inputs
      for input_value in input_values:
        if input_value in (name, transform_type):
          raise ValueError(
              f"Circular reference detected: Transform {name} "
              f"references itself as input in {identify_object(spec)}")

View on GitHub (pinned to 12126d8942)