{"record":{"id":"a9b4fa6379303b93","repo":"apache/beam","slug":"the-setup-file-option-expects-the-full-path-to-a-file-named","errorCode":null,"errorMessage":"The --setup_file option expects the full path to a file named setup.py or pyproject.toml instead of %s","messagePattern":"The --setup_file option expects the full path to a file named setup\\.py or pyproject\\.toml instead of (.+?)","errorType":"validation","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/runners/portability/stager.py","lineNumber":306,"sourceCode":"          setup_options.requirements_file is not None or pypi_requirements):\n        for pkg in packages_to_stage:\n          pkg_path = os.path.join(requirements_cache_path, pkg)\n          if os.path.exists(pkg_path):\n            resources.append(\n                Stager._create_file_stage_to_artifact(pkg_path, pkg))\n\n      # Handle a setup file if present.\n      # We will build the setup package locally and then copy it to the staging\n      # location because the staging location is a remote path and the file\n      # cannot be created directly there.\n      if setup_options.setup_file is not None:\n        if not os.path.isfile(setup_options.setup_file):\n          raise RuntimeError(\n              'The file %s cannot be found. It was specified in the '\n              '--setup_file command line option.' % setup_options.setup_file)\n        if os.path.basename(setup_options.setup_file) not in ('setup.py',\n                                                              'pyproject.toml'):\n          raise RuntimeError(\n              'The --setup_file option expects the full path to a file named '\n              'setup.py or pyproject.toml instead of %s' %\n              setup_options.setup_file)\n        tarball_file = Stager._build_setup_package(\n            setup_options.setup_file, temp_dir, build_setup_args)\n        resources.append(\n            Stager._create_file_stage_to_artifact(\n                tarball_file, WORKFLOW_TARBALL_FILE))\n\n      if setup_options.files_to_stage is not None:\n        for file in setup_options.files_to_stage:\n          resources.append(\n              Stager._create_file_stage_to_artifact(\n                  file, os.path.basename(file)))\n\n      # Handle extra local packages that should be staged.\n      if setup_options.extra_packages is not None:\n        resources.extend(","sourceCodeStart":288,"sourceCodeEnd":324,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/runners/portability/stager.py#L288-L324","documentation":"Beam's Stager validates that --setup_file is a full path whose basename is exactly setup.py or pyproject.toml. Any other basename (e.g. my_setup.py, a directory path, a requirements file) triggers this RuntimeError.","triggerScenarios":"create_job_resources with setup_file set, file exists, but os.path.basename(setup_options.setup_file) is not 'setup.py' or 'pyproject.toml'.","commonSituations":"Passing requirements.txt or a wheel instead of setup.py; passing only the directory containing setup.py; renaming the setup file; passing a relative filename like ./setup.py is fine but 'pkg/setup.cfg' is not.","solutions":["Pass the full path to a file literally named setup.py or pyproject.toml","Rename your build file to setup.py (or use pyproject.toml) and pass its absolute path","If you meant to list dependencies without a setup file, unset setup_file and use --requirements_file instead"],"exampleFix":"// before\n--setup_file=/path/to/my_requirements.txt\n// after\n--setup_file=/path/to/project/setup.py","handlingStrategy":"validation","validationCode":"import os\nsf = '/abs/path/to/setup.py'\nassert os.path.basename(sf) in ('setup.py', 'pyproject.toml'), sf","typeGuard":"def is_valid_setup_file(p): return os.path.basename(p) in ('setup.py', 'pyproject.toml')","tryCatchPattern":"try:\n    stager.create_job_resources(setup_options, temp_dir)\nexcept RuntimeError as e:\n    if 'expects the full path to a file named setup.py' in str(e):\n        sys.exit('Rename to setup.py or use pyproject.toml')\n    raise","preventionTips":["Name your build file setup.py or pyproject.toml — no custom names","Use --requirements_file for dependency lists instead of misusing setup_file","Pass the full file path, not the directory"],"tags":["python","cli","validation","beam"],"backgroundTag":"invalid-cli-argument","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}