{"record":{"id":"fbecf35f94c574da","repo":"apache/beam","slug":"the-file-s-cannot-be-found-it-was-specified-in-the-extra","errorCode":null,"errorMessage":"The file %s cannot be found. It was specified in the --extra_packages command line option.","messagePattern":"The file (.+?) cannot be found\\. It was specified in the --extra_packages command line option\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/runners/portability/stager.py","lineNumber":651,"sourceCode":"        raise RuntimeError(\n            'The --extra_package option expects a full path ending with '\n            '\".tar\", \".tar.gz\", \".whl\" or \".zip\" instead of %s' % package)\n      if os.path.basename(package).endswith('.whl'):\n        _LOGGER.warning(\n            'The .whl package \"%s\" provided in --extra_package '\n            'must be binary-compatible with the worker runtime environment.' %\n            package)\n\n      if not os.path.isfile(package):\n        if Stager._is_remote_path(package):\n          # Download remote package.\n          _LOGGER.info(\n              'Downloading extra package: %s locally before staging', package)\n          _, last_component = FileSystems.split(package)\n          local_file_path = FileSystems.join(staging_temp_dir, last_component)\n          Stager._download_file(package, local_file_path)\n        else:\n          raise RuntimeError(\n              'The file %s cannot be found. It was specified in the '\n              '--extra_packages command line option.' % package)\n      else:\n        local_packages.append(package)\n\n    local_packages.extend([\n        FileSystems.join(staging_temp_dir, f)\n        for f in os.listdir(staging_temp_dir)\n    ])\n\n    for package in local_packages:\n      basename = os.path.basename(package)\n      resources.append(Stager._create_file_stage_to_artifact(package, basename))\n    # Create a file containing the list of extra packages and stage it.\n    # The file is important so that in the worker the packages are installed\n    # exactly in the order specified. This approach will avoid extra PyPI\n    # requests. For example if package A depends on package B and package A\n    # is installed first then the installer will try to satisfy the","sourceCodeStart":633,"sourceCodeEnd":669,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/runners/portability/stager.py#L633-L669","documentation":"Raised in Stager._create_extra_packages when an entry in the --extra_packages option cannot be located. The stager downloads each extra package from a remote path (GCS, etc.) before staging; if the resolved path is neither a local file nor downloadable, staging aborts. This guarantees the job never launches missing a dependency it was explicitly told to include.","triggerScenarios":"Passing --extra_packages with a gs:// or other remote URL whose file does not exist, or a local path that does not exist on the machine launching the job (the source region raises when the package path is not a local file and no download is possible).","commonSituations":"Typos in the wheel/tar.gz path; deleting the artifact after building it; launching from a different machine/directory than where extra packages were built; GCS object renamed or bucket permissions blocking download.","solutions":["Verify each --extra_packages path exists (local path or gs:// object) before launching the pipeline","Build the extra package wheel and re-upload it to the referenced location","Use a local file path accessible from the launch machine instead of a stale remote path","Check bucket credentials/permissions if the package lives on GCS"],"exampleFix":"# before\n--extra_packages=gs://my-bucket/pkg/dist/my_dep-0.1-py3-none-any.whl  # object never uploaded\n# after\npip wheel ./my_dep -w dist/ && gsutil cp dist/my_dep-0.1-py3-none-any.whl gs://my-bucket/pkg/dist/","handlingStrategy":"validation","validationCode":"import os\nfrom apache_beam.io.filesystems import FileSystems\nfor pkg in extra_packages:\n    if not os.path.exists(pkg) and not FileSystems.exists(pkg):\n        raise FileNotFoundError(f'--extra_packages entry missing: {pkg}')","typeGuard":"def package_exists(path: str) -> bool:\n    return os.path.isfile(path) or FileSystems.exists(path)","tryCatchPattern":"try:\n    run_pipeline(options)\nexcept RuntimeError as e:\n    if 'cannot be found' in str(e) and '--extra_packages' in str(e):\n        sys.exit('Fix or remove the missing --extra_packages entry, then relaunch.')\n    raise","preventionTips":["Stat every extra-package path (local or gs://) before submitting the job","Build and upload extra wheels in the same CI step that launches the pipeline","Use canonical, immutable artifact paths (versioned wheels) instead of mutable locations"],"tags":["python","apache-beam","staging","file-not-found"],"backgroundTag":"file-not-found","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T21:17:11.552Z"}