{"record":{"id":"95ff188c3848a043","repo":"apache/beam","slug":"the-file-s-cannot-be-found-it-was-specified-in-the-setup","errorCode":null,"errorMessage":"The file %s cannot be found. It was specified in the --setup_file command line option.","messagePattern":"The file (.+?) cannot be found\\. It was specified in the --setup_file command line option\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/runners/portability/stager.py","lineNumber":301,"sourceCode":"              setup_options.requirements_cache_only_sources)\n          if downloaded_packages:\n            packages_to_stage.update(downloaded_packages)\n\n      if (setup_options.requirements_cache != SKIP_REQUIREMENTS_CACHE) and (\n          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(","sourceCodeStart":283,"sourceCodeEnd":319,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/runners/portability/stager.py#L283-L319","documentation":"Beam's Stager.create_job_resources raises this RuntimeError when --setup_file points to a path that does not exist as a regular file on local disk. The setup_file is the setup.py/pyproject.toml used to build the workflow's dependency tarball, so staging cannot proceed without it.","triggerScenarios":"Calling create_job_resources/create_and_stage_job_resources with SetupOptions.setup_file set to a path where os.path.isfile() is False (missing file, typo, relative path from wrong working directory).","commonSituations":"Typo in the path; running the pipeline from a different directory than assumed; passing a directory instead of a file; using a path on the driver machine when launching from another environment or container.","solutions":["Fix the --setup_file path to the absolute path of an existing setup.py or pyproject.toml","Run `ls -l <path>` on the driver machine to confirm the file exists","Use os.path.abspath/expanduser when constructing the path","Verify the working directory of the process launching the job"],"exampleFix":"// before\noptions.view_as(SetupOptions).setup_file = 'setup.py'\n// after\noptions.view_as(SetupOptions).setup_file = '/abs/path/to/setup.py'","handlingStrategy":"validation","validationCode":"import os\nsetup_file = '/abs/path/to/setup.py'\nif not os.path.isfile(setup_file):\n    raise SystemExit(f'--setup_file does not exist: {setup_file}')","typeGuard":"def has_setup_file(p): return isinstance(p, str) and os.path.isfile(p)","tryCatchPattern":"try:\n    Stager.create_and_stage_job_resources(setup_options)\nexcept RuntimeError as e:\n    if 'cannot be found' in str(e) and '--setup_file' in str(e):\n        sys.exit(f'Fix --setup_file path: {e}')\n    raise","preventionTips":["Always pass absolute paths via os.path.abspath","os.path.isfile-check the path in a launch script before submitting","Remember the path must exist on the machine running the pipeline"],"tags":["python","cli","file-not-found","beam"],"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-14T16:17:12.679Z"}