apache/beam · error · RuntimeError

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

Error message

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

What it means

Raised in Stager._create_extra_packages when an entry in the --extra_packages option cannot be located. The stager downloads each extra package from a remote path (GCS, etc.) before staging; if the resolved path is neither a local file nor downloadable, staging aborts. This guarantees the job never launches missing a dependency it was explicitly told to include.

Source

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

        raise RuntimeError(
            'The --extra_package option expects a full path ending with '
            '".tar", ".tar.gz", ".whl" or ".zip" instead of %s' % package)
      if os.path.basename(package).endswith('.whl'):
        _LOGGER.warning(
            'The .whl package "%s" provided in --extra_package '
            'must be binary-compatible with the worker runtime environment.' %
            package)

      if not os.path.isfile(package):
        if Stager._is_remote_path(package):
          # Download remote package.
          _LOGGER.info(
              'Downloading extra package: %s locally before staging', package)
          _, last_component = FileSystems.split(package)
          local_file_path = FileSystems.join(staging_temp_dir, last_component)
          Stager._download_file(package, local_file_path)
        else:
          raise RuntimeError(
              'The file %s cannot be found. It was specified in the '
              '--extra_packages command line option.' % package)
      else:
        local_packages.append(package)

    local_packages.extend([
        FileSystems.join(staging_temp_dir, f)
        for f in os.listdir(staging_temp_dir)
    ])

    for package in local_packages:
      basename = os.path.basename(package)
      resources.append(Stager._create_file_stage_to_artifact(package, basename))
    # Create a file containing the list of extra packages and stage it.
    # The file is important so that in the worker the packages are installed
    # exactly in the order specified. This approach will avoid extra PyPI
    # requests. For example if package A depends on package B and package A
    # is installed first then the installer will try to satisfy the

View on GitHub (pinned to 12126d8942)

Solutions

1. Verify each --extra_packages path exists (local path or gs:// object) before launching the pipeline
2. Build the extra package wheel and re-upload it to the referenced location
3. Use a local file path accessible from the launch machine instead of a stale remote path
4. Check bucket credentials/permissions if the package lives on GCS

Example fix

# before
--extra_packages=gs://my-bucket/pkg/dist/my_dep-0.1-py3-none-any.whl  # object never uploaded
# after
pip wheel ./my_dep -w dist/ && gsutil cp dist/my_dep-0.1-py3-none-any.whl gs://my-bucket/pkg/dist/

import os
from apache_beam.io.filesystems import FileSystems
for pkg in extra_packages:
    if not os.path.exists(pkg) and not FileSystems.exists(pkg):
        raise FileNotFoundError(f'--extra_packages entry missing: {pkg}')

def package_exists(path: str) -> bool:
    return os.path.isfile(path) or FileSystems.exists(path)

try:
    run_pipeline(options)
except RuntimeError as e:
    if 'cannot be found' in str(e) and '--extra_packages' in str(e):
        sys.exit('Fix or remove the missing --extra_packages entry, then relaunch.')
    raise

When it happens

Trigger: Passing --extra_packages with a gs:// or other remote URL whose file does not exist, or a local path that does not exist on the machine launching the job (the source region raises when the package path is not a local file and no download is possible).

Common situations: Typos in the wheel/tar.gz path; deleting the artifact after building it; launching from a different machine/directory than where extra packages were built; GCS object renamed or bucket permissions blocking download.

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

• src and dst files do not exist. src: %s, dst: %s
• Artifacts not found at location: %s when using read_artifact
• Vocabulary file {} not found in artifact location
• The feature store yaml path (%s) does not exist.
• f"Error loading providers from {include_path} included at {s

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