apache/beam · error · RuntimeError

Unrecognized SDK wheel file

Error message

Unrecognized SDK wheel file: %s

What it means

Raised by Stager._desired_sdk_filename_in_staging_location when --sdk_location points to a .whl file whose basename does not start with 'apache_beam'. Only recognized Beam SDK wheels can be staged; anything else is rejected. This prevents staging an arbitrary wheel as if it were the SDK.

Solutions

  1. Point --sdk_location at a wheel whose filename starts with 'apache_beam' (e.g. apache_beam-2.xx.0-cp310-...whl)
  2. Rename/restore the Beam wheel to its canonical apache_beam-*.whl filename
  3. Use a non-wheel sdk_location (e.g. a staging directory or the default) if you meant to stage sources
  4. Verify you are not accidentally passing an unrelated .whl

Example fix

# before
--sdk_location=./dist/my_custom_pkg-1.0-py3-none-any.whl
# after
--sdk_location=./dist/apache_beam-2.60.0-cp310-cp310-manylinux1_x86_64.whl
Defensive patterns

Strategy: validation

Validate before calling

import os
sdk_location = options.get('sdk_location', '')
if sdk_location.endswith('.whl'):
    name = os.path.basename(sdk_location)
    if not name.startswith('apache_beam'):
        raise ValueError(f'{sdk_location} is not an apache_beam wheel')

Type guard

def is_beam_wheel(sdk_location: str) -> bool:
    import os
    return (not sdk_location.endswith('.whl')) or os.path.basename(sdk_location).startswith('apache_beam')

Try / catch

try:
    stage(sdk_location=sdk_location)
except RuntimeError as e:
    if 'Unrecognized SDK wheel file' in str(e):
        sys.exit('--sdk_location must point to an apache_beam-*.whl file')
    raise

Prevention

When it happens

Trigger: Running with --sdk_location=/path/to/foo.whl (or any non-apache_beam wheel filename) so the split basename fails the 'apache_beam' prefix check.

Common situations: Pointing sdk_location at a private dependency wheel by mistake; renaming a Beam wheel so the apache_beam prefix is lost; copy-pasting a wrong path into sdk_location.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

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

      if not output_files:
        raise RuntimeError(
            'File %s not found.' % os.path.join(temp_dir, '*.tar.gz'))
      return output_files[0]
    finally:
      os.chdir(saved_current_directory)

  @staticmethod
  def _desired_sdk_filename_in_staging_location(sdk_location) -> str:
    """Returns the name that SDK file should have in the staging location.
      Args:
        sdk_location: Full path to SDK file.
      """
    if sdk_location.endswith('.whl'):
      _, wheel_filename = FileSystems.split(sdk_location)
      if wheel_filename.startswith('apache_beam'):
        return wheel_filename
      else:
        raise RuntimeError('Unrecognized SDK wheel file: %s' % sdk_location)
    else:
      return names.STAGED_SDK_SOURCES_FILENAME

  @staticmethod
  def _create_beam_sdk(
      sdk_remote_location,
      temp_dir) -> list[beam_runner_api_pb2.ArtifactInformation]:
    """Creates a Beam SDK file with the appropriate version.

      Args:
        sdk_remote_location: A URL from which the file can be downloaded or a
          remote file location. The SDK file can be a tarball or a wheel.
        temp_dir: path to temporary location where the file should be
          downloaded.

      Returns:
        A list of ArtifactInformation of local files path and SDK files that
        will be staged to the staging location.

View on GitHub (pinned to 12126d8942)