apache/beam · error · RuntimeError

Failed to build package from

Error message

Failed to build package from '{setup_file}' using . 'python -m build'. Please ensure that the 'build' module is installed and your project's build configuration is valid.

What it means

Raised by Stager._build_setup_package when building a setup.py-less project (pyproject.toml only) via 'python -m build' fails. There is no setuptools legacy fallback for pyproject-only projects, so staging aborts. The message points at a missing 'build' module or an invalid build configuration.

Solutions

Install the build module in the environment (pip install build)
Fix errors reported by 'python -m build' by running it manually in the project directory
Add a working build-system section to pyproject.toml, or provide a setup.py for the legacy fallback path
Pin a compatible setuptools/wheel/build version in the build environment

Example fix

# before
$ python stager.py --setup_file=/proj/pyproject.toml-only  # 'build' not installed -> RuntimeError
# after
$ pip install build && python -m build /proj  # verify locally before staging

Defensive patterns

Strategy: try-catch

Validate before calling

import importlib.util, subprocess
if importlib.util.find_spec('build') is None:
    raise SystemExit("Install the 'build' module: pip install build")
subprocess.run(['python', '-m', 'build', setup_dir], check=True)  # fail fast locally

Type guard

def build_tool_available() -> bool:
    import importlib.util
    return importlib.util.find_spec('build') is not None

Try / catch

try:
    stage(setup_file=setup_file)
except RuntimeError as e:
    if "python -m build" in str(e):
        subprocess.run(['pip', 'install', 'build'], check=True)
        stage(setup_file=setup_file)
    else:
        raise

Prevention

pip install build in every environment that stages setup_file packages
Run 'python -m build .' locally before submitting pipelines
Keep a valid [build-system] table in pyproject.toml or ship a setup.py fallback

When it happens

Trigger: Using --setup_file pointing at a project with only pyproject.toml while the 'build' package is not installed, or when 'python -m build' exits nonzero due to a broken build configuration.

Common situations: Custom source container builds with modern pyproject-only packages; forgetting to 'pip install build' in the staging environment; pyproject.toml with invalid metadata or failing build backend.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

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

Appendix: source

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

              os.path.dirname(setup_file),
          ]
          _LOGGER.info('Executing command: %s', build_setup_args)
          processes.check_output(build_setup_args)
        except RuntimeError:
          if setup_file.endswith('setup.py'):
            build_setup_args = [
                Stager._get_python_executable(),
                os.path.basename(setup_file),
                'sdist',
                '--dist-dir',
                temp_dir
            ]
            _LOGGER.info('Executing command: %s', build_setup_args)
            processes.check_output(build_setup_args)
          else:
            # If it's pyproject.toml and `python -m build` failed,
            # there's no direct legacy fallback.
            raise RuntimeError(
                f"Failed to build package from '{setup_file}' using . "
                f"'python -m build'. Please ensure that the 'build' module "
                f"is installed and your project's build configuration is valid."
            )
      output_files = glob.glob(os.path.join(temp_dir, '*.tar.gz'))
      if not output_files:
        raise RuntimeError(
            'File %s not found.' % os.path.join(temp_dir, '*.tar.gz'))
      return output_files[0]
    finally:
      os.chdir(saved_current_directory)

  @staticmethod
  def _desired_sdk_filename_in_staging_location(sdk_location) -> str:
    """Returns the name that SDK file should have in the staging location.
      Args:
        sdk_location: Full path to SDK file.
      """

View on GitHub (pinned to 12126d8942)