apache/beam · error · RuntimeError

The file %s cannot be found. It was specified in the --setup

Error message

The file %s cannot be found. It was specified in the --setup_file command line option.

What it means

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.

Source

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

              setup_options.requirements_cache_only_sources)
          if downloaded_packages:
            packages_to_stage.update(downloaded_packages)

      if (setup_options.requirements_cache != SKIP_REQUIREMENTS_CACHE) and (
          setup_options.requirements_file is not None or pypi_requirements):
        for pkg in packages_to_stage:
          pkg_path = os.path.join(requirements_cache_path, pkg)
          if os.path.exists(pkg_path):
            resources.append(
                Stager._create_file_stage_to_artifact(pkg_path, pkg))

      # Handle a setup file if present.
      # We will build the setup package locally and then copy it to the staging
      # location because the staging location is a remote path and the file
      # cannot be created directly there.
      if setup_options.setup_file is not None:
        if not os.path.isfile(setup_options.setup_file):
          raise RuntimeError(
              'The file %s cannot be found. It was specified in the '
              '--setup_file command line option.' % setup_options.setup_file)
        if os.path.basename(setup_options.setup_file) not in ('setup.py',
                                                              'pyproject.toml'):
          raise RuntimeError(
              'The --setup_file option expects the full path to a file named '
              'setup.py or pyproject.toml instead of %s' %
              setup_options.setup_file)
        tarball_file = Stager._build_setup_package(
            setup_options.setup_file, temp_dir, build_setup_args)
        resources.append(
            Stager._create_file_stage_to_artifact(
                tarball_file, WORKFLOW_TARBALL_FILE))

      if setup_options.files_to_stage is not None:
        for file in setup_options.files_to_stage:
          resources.append(
              Stager._create_file_stage_to_artifact(

View on GitHub (pinned to 12126d8942)

Solutions

1. Fix the --setup_file path to the absolute path of an existing setup.py or pyproject.toml
2. Run `ls -l <path>` on the driver machine to confirm the file exists
3. Use os.path.abspath/expanduser when constructing the path
4. Verify the working directory of the process launching the job

Example fix

// before
options.view_as(SetupOptions).setup_file = 'setup.py'
// after
options.view_as(SetupOptions).setup_file = '/abs/path/to/setup.py'

import os
setup_file = '/abs/path/to/setup.py'
if not os.path.isfile(setup_file):
    raise SystemExit(f'--setup_file does not exist: {setup_file}')

def has_setup_file(p): return isinstance(p, str) and os.path.isfile(p)

try:
    Stager.create_and_stage_job_resources(setup_options)
except RuntimeError as e:
    if 'cannot be found' in str(e) and '--setup_file' in str(e):
        sys.exit(f'Fix --setup_file path: {e}')
    raise

When it happens

Trigger: 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).

Common situations: 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.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• The file "%s" cannot be found. Its location was specified by
• The file %s cannot be found. It was specified in the --exper
• The --setup_file option expects the full path to a file name
• The --sdk_location option was used with an unsupported type
• The --experiment='jar_packages=' option expects a full path

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