apache/beam · error · RuntimeError

The --extra_package option expects a full path ending with "

Error message

The --extra_package option expects a full path ending with ".tar", ".tar.gz", ".whl" or ".zip" instead of %s

What it means

Stager._create_jar_packages' sibling _create_extra_packages validates that every --extra_package entry has basename ending in .tar, .tar.gz, .whl or .zip (the formats the Python SDK container can install). Other extensions raise this RuntimeError.

Source

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

      Returns:
        A list of ArtifactInformation of local file paths and file names
        (no paths) for the resources staged. All the files are assumed to be
        staged in staging_location.

      Raises:
        RuntimeError: If files specified are not found or do not have expected
          name patterns.
      """
    resources: list[beam_runner_api_pb2.ArtifactInformation] = []
    staging_temp_dir = tempfile.mkdtemp(dir=temp_dir)
    local_packages: list[str] = []
    for package in extra_packages:
      if not (os.path.basename(package).endswith('.tar') or
              os.path.basename(package).endswith('.tar.gz') or
              os.path.basename(package).endswith('.whl') or
              os.path.basename(package).endswith('.zip')):
        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(

View on GitHub (pinned to 12126d8942)

Solutions

1. Repackage the dependency as a .tar.gz sdist, .whl, .zip, or .tar and pass its full path
2. For Java jars use --experiment=jar_packages=... instead of extra_package
3. If you have a .tar.bz2, recompress to .tar.gz; for .egg, build a wheel (pip wheel) instead
4. Ensure the path basename (not the full string) carries the extension

Example fix

// before
--extra_package=/libs/my-dep.egg
// after
--extra_package=/libs/my_dep-1.0-py3-none-any.whl

extra = options.view_as(SetupOptions).extra_packages or []
bad = [p for p in extra if os.path.basename(p).rsplit('.', 1)[-1]
       not in ('tar', 'gz', 'whl', 'zip')]
if bad:
    raise SystemExit(f'extra_package must be .tar/.tar.gz/.whl/.zip: {bad}')

def is_extra_package(p):
    b = os.path.basename(p)
    return b.endswith(('.tar', '.tar.gz', '.whl', '.zip'))

try:
    stager.create_and_stage_job_resources(setup_options)
except RuntimeError as e:
    if '--extra_package option expects' in str(e):
        sys.exit(f'Repackage dependency: {e}')
    raise

When it happens

Trigger: create_job_resources with options.extra_packages containing an entry whose basename lacks one of the accepted extensions.

Common situations: Passing a .jar, .egg, .tar.bz2, or a directory; passing a Windows-built sdist with unexpected extension; confusion between jar_packages and extra_package options.

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 --setup_file option expects the full path to a file name
• The --experiment='jar_packages=' option expects a full path
• 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/39bdfaf2c0f52690. Report an issue: GitHub.