apache/beam · error · RuntimeError

The --sdk_location option was used with an unsupported type

Error message

The --sdk_location option was used with an unsupported type of location: %s

What it means

create_job_resources wraps any failure to build or fetch an SDK tarball from --sdk_location in this RuntimeError, so the unsupported-location message can mask the underlying exception (the bare except re-raises with no chaining). The location was neither a local file, a supported remote URL, nor 'default'.

Source

Thrown at sdks/python/apache_beam/runners/portability/stager.py:338

                  file, os.path.basename(file)))

      # Handle extra local packages that should be staged.
      if setup_options.extra_packages is not None:
        resources.extend(
            Stager._create_extra_packages(
                setup_options.extra_packages, temp_dir=temp_dir))

      if hasattr(setup_options, 'sdk_location'):
        sdk_location = setup_options.sdk_location
        if Stager._is_remote_path(sdk_location):
          try:
            resources.extend(
                Stager._create_beam_sdk(
                    sdk_remote_location=setup_options.sdk_location,
                    temp_dir=temp_dir,
                ))
          except:
            raise RuntimeError(
                'The --sdk_location option was used with an unsupported '
                'type of location: %s' % sdk_location)

        elif sdk_location == 'default':
          # Use default location for a runner.
          pass
        elif sdk_location == 'container':
          # Used in the past to indicate that SDK should be used from container
          # image instead of being staged.
          # Equivalent to 'default' now, leaving for backwards compatibility.
          pass
        else:
          if os.path.isdir(setup_options.sdk_location):
            sdk_path = os.path.join(
                setup_options.sdk_location, names.STAGED_SDK_SOURCES_FILENAME)
          else:
            sdk_path = setup_options.sdk_location

View on GitHub (pinned to 12126d8942)

Solutions

1. Print/inspect the chained failure: run with sdk_location temporarily set to a valid local tarball to isolate the cause
2. Set --sdk_location to a valid value: 'default', an empty string (skip staging), a local .tar.gz path, or a reachable https:// URL to a Beam SDK tarball
3. Verify the URL is downloadable (curl -I) and names a Beam SDK tar.gz
4. Check that required Beam filesystem plugins/dependencies (e.g. gcsfs) are installed if using a remote scheme

Example fix

// before
--sdk_location=gs://my-bucket/sdks/  (directory, not a tarball)
// after
--sdk_location=gs://my-bucket/sdks/apache_beam-2.60.0.tar.gz

try:
    Stager.create_and_stage_job_resources(setup_options)
except RuntimeError as e:
    if 'unsupported type of location' in str(e):
        logging.warning('sdk_location rejected; retrying with default', exc_info=True)
        setup_options.sdk_location = 'default'
        Stager.create_and_stage_job_resources(setup_options)
    else:
        raise

When it happens

Trigger: --sdk_location set to a value that _create_beam_sdk cannot handle (bad scheme, unreachable URL, corrupt remote path) causing an exception inside the try block.

Common situations: Typo in a gs:// or https:// SDK location; pointing at a directory rather than a tarball; network failure downloading the SDK; using an SDK location scheme not supported by the filesystems installed.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• The file %s cannot be found. It was specified in the --setup
• The --setup_file option expects the full path to a file name
• The file "%s" cannot be found. Its location was specified by
• The staging_location must be specified.
• The --experiment='jar_packages=' option expects a full path

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