{"record":{"id":"5c3dcc65e5fa9cbf","repo":"apache/beam","slug":"unrecognized-sdk-wheel-file-s","errorCode":null,"errorMessage":"Unrecognized SDK wheel file: %s","messagePattern":"Unrecognized SDK wheel file: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/runners/portability/stager.py","lineNumber":915,"sourceCode":"      if not output_files:\n        raise RuntimeError(\n            'File %s not found.' % os.path.join(temp_dir, '*.tar.gz'))\n      return output_files[0]\n    finally:\n      os.chdir(saved_current_directory)\n\n  @staticmethod\n  def _desired_sdk_filename_in_staging_location(sdk_location) -> str:\n    \"\"\"Returns the name that SDK file should have in the staging location.\n      Args:\n        sdk_location: Full path to SDK file.\n      \"\"\"\n    if sdk_location.endswith('.whl'):\n      _, wheel_filename = FileSystems.split(sdk_location)\n      if wheel_filename.startswith('apache_beam'):\n        return wheel_filename\n      else:\n        raise RuntimeError('Unrecognized SDK wheel file: %s' % sdk_location)\n    else:\n      return names.STAGED_SDK_SOURCES_FILENAME\n\n  @staticmethod\n  def _create_beam_sdk(\n      sdk_remote_location,\n      temp_dir) -> list[beam_runner_api_pb2.ArtifactInformation]:\n    \"\"\"Creates a Beam SDK file with the appropriate version.\n\n      Args:\n        sdk_remote_location: A URL from which the file can be downloaded or a\n          remote file location. The SDK file can be a tarball or a wheel.\n        temp_dir: path to temporary location where the file should be\n          downloaded.\n\n      Returns:\n        A list of ArtifactInformation of local files path and SDK files that\n        will be staged to the staging location.","sourceCodeStart":897,"sourceCodeEnd":933,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/runners/portability/stager.py#L897-L933","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Point --sdk_location at a wheel whose filename starts with 'apache_beam' (e.g. apache_beam-2.xx.0-cp310-...whl)","Rename/restore the Beam wheel to its canonical apache_beam-*.whl filename","Use a non-wheel sdk_location (e.g. a staging directory or the default) if you meant to stage sources","Verify you are not accidentally passing an unrelated .whl"],"exampleFix":"# before\n--sdk_location=./dist/my_custom_pkg-1.0-py3-none-any.whl\n# after\n--sdk_location=./dist/apache_beam-2.60.0-cp310-cp310-manylinux1_x86_64.whl","handlingStrategy":"validation","validationCode":"import os\nsdk_location = options.get('sdk_location', '')\nif sdk_location.endswith('.whl'):\n    name = os.path.basename(sdk_location)\n    if not name.startswith('apache_beam'):\n        raise ValueError(f'{sdk_location} is not an apache_beam wheel')","typeGuard":"def is_beam_wheel(sdk_location: str) -> bool:\n    import os\n    return (not sdk_location.endswith('.whl')) or os.path.basename(sdk_location).startswith('apache_beam')","tryCatchPattern":"try:\n    stage(sdk_location=sdk_location)\nexcept RuntimeError as e:\n    if 'Unrecognized SDK wheel file' in str(e):\n        sys.exit('--sdk_location must point to an apache_beam-*.whl file')\n    raise","preventionTips":["Never rename Beam wheels; keep the canonical apache_beam-*.whl filename","Double-check the sdk_location path points at the Beam SDK, not another dependency","Validate sdk_location in launch scripts before submission"],"tags":["python","apache-beam","wheel","sdk-location"],"backgroundTag":"invalid-argument-value","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}