apache/beam · error · ValueError

Cannot find SDK builder type

Error message

Cannot find SDK builder type {key} in {available_builder_keys}

What it means

SdkContainerImageBuilder._get_subclass_by_key looks up a registered container-image builder subclass by its builder key. If no subclass matches the requested key, it raises ValueError listing all available builder keys so the caller can pick a valid one.

Solutions

Use one of the keys listed in the error message verbatim
Check the Beam docs/source for valid SdkContainerImageBuilder keys for your version
Upgrade apache-beam if the desired builder key only exists in newer releases
If using a custom builder, ensure its module is imported so the subclass registers

Example fix

// before
builder = SdkContainerImageBuilder._get_subclass_by_key('cloudbuild')
// after
builder = SdkContainerImageBuilder._get_subclass_by_key('cloud_build')

Defensive patterns

Strategy: validation

Validate before calling

available = [s._builder_key() for s in SdkContainerImageBuilder.get_all_subclasses()]
assert key in available, f'{key!r} not a valid builder key; pick from {available}'

Type guard

def is_known_builder_key(key: str) -> bool:
    return key in {s._builder_key() for s in SdkContainerImageBuilder.get_all_subclasses()}

Try / catch

try:
    builder = SdkContainerImageBuilder._get_subclass_by_key(key)
except ValueError as e:
    logger.error('Invalid SDK builder key %s: %s', key, e)
    builder = SdkContainerImageBuilder._get_subclass_by_key('local')  # sane default

Prevention

Copy builder keys from the Beam version you pinned, not from docs for another version
Enumerate get_all_subclasses() keys at startup in scripts that parameterize the key
Pin your apache-beam version so key names can't drift under you

When it happens

Trigger: Calling build_container_image (viaSdkContainerBuilder) with an sdk_builder key string that no registered _SdkContainerImage*Builder subclass claims, e.g. passing 'docker' or 'cloud_build' misspelled or unsupported for the SDK version.

Common situations: Typos in the container build option; using a builder key introduced in a newer Beam version than installed; custom subclass not imported/registered so get_all_subclasses doesn't see it.

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/84bec08503976097. Report an issue: GitHub.

Appendix: source

Thrown at sdks/python/apache_beam/runners/portability/sdk_container_builder.py:150

  @classmethod
  def build_container_image(cls, pipeline_options: PipelineOptions) -> str:
    setup_options = pipeline_options.view_as(SetupOptions)
    container_build_engine = setup_options.prebuild_sdk_container_engine
    builder_cls = cls._get_subclass_by_key(container_build_engine)
    builder = builder_cls(pipeline_options)
    return builder._build()

  @classmethod
  def _get_subclass_by_key(cls, key: str) -> type['SdkContainerImageBuilder']:
    available_builders = [
        subclass for subclass in cls.get_all_subclasses()
        if subclass._builder_key() == key
    ]
    if not available_builders:
      available_builder_keys = [
          subclass._builder_key() for subclass in cls.get_all_subclasses()
      ]
      raise ValueError(
          f'Cannot find SDK builder type {key} in '
          f'{available_builder_keys}')
    elif len(available_builders) > 1:
      raise ValueError(f'Found multiple builders under key {key}')
    return available_builders[0]


class _SdkContainerImageLocalBuilder(SdkContainerImageBuilder):
  """SdkContainerLocalBuilder builds the sdk container image with local
  docker."""
  @classmethod
  def _builder_key(cls):
    return 'local_docker'

  def _invoke_docker_build_and_push(self, container_image_name):
    try:
      _LOGGER.info("Building sdk container, this may take a few minutes...")
      now = time.time()

View on GitHub (pinned to 12126d8942)