apache/beam · error · RuntimeError

File not found.

Error message

File %s not found.

What it means

Raised by Stager._build_setup_package after a (seemingly successful) build when no *.tar.gz artifact was produced in the temporary build directory. It catches builds that complete without emitting a source distribution. The raised message reports the glob pattern, not a specific file.

Solutions

  1. Ensure the project's build produces a source distribution (sdist .tar.gz) in the build directory
  2. Run 'python setup.py sdist' manually to confirm a tar.gz is generated
  3. Check setup.cfg/pyproject.toml for settings that redirect build output
  4. Update Beam or inspect Stager._build_setup_package if a backend change relocated artifacts

Example fix

# before
# setup.cfg omitted sdist; only bdist_wheel ran -> 'File .../*.tar.gz not found.'
# after
[bdist_wheel]
universal = 0
# plus ensure: python setup.py sdist  (or 'python -m build --sdist') succeeds in the project dir
Defensive patterns

Strategy: validation

Validate before calling

import subprocess, glob, os
def sdist_produces_tarball(setup_dir):
    tmp = '/tmp/_sdist_check'
    subprocess.run(['python', 'setup.py', 'sdist', '--dist-dir', tmp], cwd=setup_dir, check=True)
    return bool(glob.glob(os.path.join(tmp, '*.tar.gz')))
assert sdist_produces_tarball('/path/to/project'), 'Project does not produce an sdist .tar.gz'

Try / catch

try:
    stage(setup_file=setup_file)
except RuntimeError as e:
    if 'not found' in str(e) and '*.tar.gz' in str(e):
        sys.exit('Build produced no sdist; run "python setup.py sdist" locally to debug.')
    raise

Prevention

When it happens

Trigger: --setup_file build runs but the configured build backend writes output elsewhere (or produces only wheels), leaving the temp dir without any .tar.gz file.

Common situations: Custom setup.py or build backend that skips sdist; build config redirecting dist output outside temp_dir; partially failing builds that exit 0 but produce nothing.

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

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

Appendix: source

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

                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.
      """
    if sdk_location.endswith('.whl'):
      _, wheel_filename = FileSystems.split(sdk_location)
      if wheel_filename.startswith('apache_beam'):
        return wheel_filename
      else:
        raise RuntimeError('Unrecognized SDK wheel file: %s' % sdk_location)
    else:

View on GitHub (pinned to 12126d8942)