{"record":{"id":"17208fef912ed5be","repo":"apache/beam","slug":"failed-to-build-package-from-setup-file-using-python-m-build","errorCode":null,"errorMessage":"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.","messagePattern":"Failed to build package from '(.+?)' using \\. 'python -m build'\\. Please ensure that the 'build' module is installed and your project's build configuration is valid\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/runners/portability/stager.py","lineNumber":891,"sourceCode":"              os.path.dirname(setup_file),\n          ]\n          _LOGGER.info('Executing command: %s', build_setup_args)\n          processes.check_output(build_setup_args)\n        except RuntimeError:\n          if setup_file.endswith('setup.py'):\n            build_setup_args = [\n                Stager._get_python_executable(),\n                os.path.basename(setup_file),\n                'sdist',\n                '--dist-dir',\n                temp_dir\n            ]\n            _LOGGER.info('Executing command: %s', build_setup_args)\n            processes.check_output(build_setup_args)\n          else:\n            # If it's pyproject.toml and `python -m build` failed,\n            # there's no direct legacy fallback.\n            raise RuntimeError(\n                f\"Failed to build package from '{setup_file}' using . \"\n                f\"'python -m build'. Please ensure that the 'build' module \"\n                f\"is installed and your project's build configuration is valid.\"\n            )\n      output_files = glob.glob(os.path.join(temp_dir, '*.tar.gz'))\n      if not output_files:\n        raise RuntimeError(\n            'File %s not found.' % os.path.join(temp_dir, '*.tar.gz'))\n      return output_files[0]\n    finally:\n      os.chdir(saved_current_directory)\n\n  @staticmethod\n  def _desired_sdk_filename_in_staging_location(sdk_location) -> str:\n    \"\"\"Returns the name that SDK file should have in the staging location.\n      Args:\n        sdk_location: Full path to SDK file.\n      \"\"\"","sourceCodeStart":873,"sourceCodeEnd":909,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/runners/portability/stager.py#L873-L909","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\n$ python stager.py --setup_file=/proj/pyproject.toml-only  # 'build' not installed -> RuntimeError\n# after\n$ pip install build && python -m build /proj  # verify locally before staging","handlingStrategy":"try-catch","validationCode":"import importlib.util, subprocess\nif importlib.util.find_spec('build') is None:\n    raise SystemExit(\"Install the 'build' module: pip install build\")\nsubprocess.run(['python', '-m', 'build', setup_dir], check=True)  # fail fast locally","typeGuard":"def build_tool_available() -> bool:\n    import importlib.util\n    return importlib.util.find_spec('build') is not None","tryCatchPattern":"try:\n    stage(setup_file=setup_file)\nexcept RuntimeError as e:\n    if \"python -m build\" in str(e):\n        subprocess.run(['pip', 'install', 'build'], check=True)\n        stage(setup_file=setup_file)\n    else:\n        raise","preventionTips":["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"],"tags":["python","apache-beam","packaging","build"],"backgroundTag":"missing-dependency","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}