apache/beam · error · RuntimeError

The --setup_file option expects the full path to a file name

Error message

The --setup_file option expects the full path to a file named setup.py or pyproject.toml instead of %s

What it means

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.

Source

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

          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(
                  file, os.path.basename(file)))

      # Handle extra local packages that should be staged.
      if setup_options.extra_packages is not None:
        resources.extend(

View on GitHub (pinned to 12126d8942)

Solutions

1. Pass the full path to a file literally named setup.py or pyproject.toml
2. Rename your build file to setup.py (or use pyproject.toml) and pass its absolute path
3. If you meant to list dependencies without a setup file, unset setup_file and use --requirements_file instead

Example fix

// before
--setup_file=/path/to/my_requirements.txt
// after
--setup_file=/path/to/project/setup.py

import os
sf = '/abs/path/to/setup.py'
assert os.path.basename(sf) in ('setup.py', 'pyproject.toml'), sf

def is_valid_setup_file(p): return os.path.basename(p) in ('setup.py', 'pyproject.toml')

try:
    stager.create_job_resources(setup_options, temp_dir)
except RuntimeError as e:
    if 'expects the full path to a file named setup.py' in str(e):
        sys.exit('Rename to setup.py or use pyproject.toml')
    raise

When it happens

Trigger: create_job_resources with setup_file set, file exists, but os.path.basename(setup_options.setup_file) is not 'setup.py' or 'pyproject.toml'.

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

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

• The --experiment='jar_packages=' option expects a full path
• The --extra_package option expects a full path ending with "
• Delimiter must be a non-empty bytes sequence.
• Delimiter must not self-overlap.
• escapechar must be bytes of size 1: '%s'

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