apache/beam · error · ValueError

Unknown environment type

Error message

Unknown environment type: %s

What it means

Environment.from_options maps a PortableOptions.environment_type string to a registered environment URN via getattr on common_urns.environments; an unknown name raises AttributeError, converted to ValueError 'Unknown environment type: %s'.

Solutions

1. Use a valid environment_type value (e.g. DOCKER, PROCESS, EXTERNAL, LOOPBACK).
2. Check the installed Beam version's common_urns.environments enum for supported names.
3. If you need a custom environment, configure environment_config with the EXTERNAL type instead.

Example fix

// before
--environment_type=cloud
// after
--environment_type=DOCKER

from apache_beam.portability.api import beam_runner_api_pb2
def valid_env_type(name):
    return name in ('DOCKER', 'PROCESS', 'EXTERNAL', 'LOOPBACK', 'EMBEDDED_PYTHON', 'EMBEDDED_GO')

try:
    env = Environment.from_options(options)
except ValueError as e:
    if str(e).startswith('Unknown environment type'): ...

When it happens

Trigger: Pipeline options specify an environment_type (e.g. --environment_type=...) that is not one of the Beam environment enum names (DOCKER, PROCESS, EXTERNAL, LOOPBACK, EMBEDDED_PYTHON, etc.).

Common situations: Typo in --environment_type, custom runner passing a free-form string, or using an environment name added in a newer Beam version than installed.

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 list of URNs for overriding transforms was provided but…
• A cannot be expanded
• can't get data to render
• cannot call getPipelineOptions() in a null context
• Class ' ' does not implement PipelineRunner. Supported…

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

Appendix: source

Thrown at sdks/python/apache_beam/transforms/environments.py:276

      options: The PortableOptions object.
    """
    if cls != Environment:
      raise NotImplementedError

    portable_options = options.view_as(PortableOptions)
    environment_type = portable_options.environment_type
    if not environment_type:
      environment_urn = common_urns.environments.DOCKER.urn
    elif environment_type.startswith('beam:env:'):
      environment_urn = environment_type
    elif environment_type == 'LOOPBACK':
      environment_urn = python_urns.EMBEDDED_PYTHON_LOOPBACK
    else:
      try:
        environment_urn = getattr(
            common_urns.environments, environment_type).urn
      except AttributeError:
        raise ValueError('Unknown environment type: %s' % environment_type)

    env_class = Environment.get_env_cls_from_urn(environment_urn)
    return env_class.from_options(portable_options)  # type: ignore


@Environment.register_urn(common_urns.environments.DEFAULT.urn, None)
class DefaultEnvironment(Environment):
  """Used as a stub when context is missing a default environment."""
  def to_runner_api_parameter(self, context):
    return common_urns.environments.DEFAULT.urn, None

  @staticmethod
  def from_runner_api_parameter(
      payload,  # type: beam_runner_api_pb2.DockerPayload
      capabilities,  # type: Iterable[str]
      artifacts,  # type: Iterable[beam_runner_api_pb2.ArtifactInformation]
      resource_hints,  # type: Mapping[str, bytes]
      context  # type: PipelineContext

View on GitHub (pinned to 12126d8942)