{"record":{"id":"c115ae9bd081e52e","repo":"apache/beam","slug":"the-experiment-jar-packages-option-expects-a-full-path","errorCode":null,"errorMessage":"The --experiment='jar_packages=' option expects a full path ending with \".jar\" instead of %s","messagePattern":"The --experiment='jar_packages=' option expects a full path ending with \"\\.jar\" instead of (.+?)","errorType":"validation","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/runners/portability/stager.py","lineNumber":573,"sourceCode":"      jar_packages, temp_dir) -> list[beam_runner_api_pb2.ArtifactInformation]:\n    \"\"\"Creates a list of local jar packages for Java SDK Harness.\n\n    :param jar_packages: Ordered list of local paths to jar packages to be\n      staged. Only packages on localfile system and GCS are supported.\n    :param temp_dir: Temporary folder where the resource building can happen.\n    :return: A list of tuples of local file paths and file names (no paths) for\n      the resource staged. All the files are assumed to be staged in\n      staging_location.\n    :raises:\n      RuntimeError: If files specified are not found or do not have expected\n        name patterns.\n    \"\"\"\n    resources: list[beam_runner_api_pb2.ArtifactInformation] = []\n    staging_temp_dir = tempfile.mkdtemp(dir=temp_dir)\n    local_packages: list[str] = []\n    for package in jar_packages:\n      if not os.path.basename(package).endswith('.jar'):\n        raise RuntimeError(\n            'The --experiment=\\'jar_packages=\\' option expects a full path '\n            'ending with \".jar\" instead of %s' % package)\n\n      if not os.path.isfile(package):\n        if Stager._is_remote_path(package):\n          # Download remote package.\n          _LOGGER.info(\n              'Downloading jar package: %s locally before staging', package)\n          _, last_component = FileSystems.split(package)\n          local_file_path = FileSystems.join(staging_temp_dir, last_component)\n          Stager._download_file(package, local_file_path)\n        else:\n          raise RuntimeError(\n              'The file %s cannot be found. It was specified in the '\n              '--experiment=\\'jar_packages=\\' command line option.' % package)\n      else:\n        local_packages.append(package)\n","sourceCodeStart":555,"sourceCodeEnd":591,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/runners/portability/stager.py#L555-L591","documentation":"For --experiment='jar_packages=...', Stager._create_jar_packages validates each entry's basename ends with '.jar'. Anything else (zip, path without extension, directory) raises this RuntimeError before any existence check.","triggerScenarios":"create_job_resources with options.jar_packages containing an item whose basename does not end with .jar.","commonSituations":"Passing a fat zip or an .aar; passing a Maven coordinate instead of a path; trailing whitespace or query string on the URL; accidentally passing a directory.","solutions":["Ensure each jar_packages entry is a full path/URL whose basename ends with .jar","Convert Maven coordinates to the actual jar URL/path","Strip whitespace/query parameters from the entry","Package other dependency types as jars or use extra_packages for tar/whl/zip Python packages"],"exampleFix":"// before\n--experiment=jar_packages=/libs/my-lib.zip\n// after\n--experiment=jar_packages=/libs/my-lib.jar","handlingStrategy":"validation","validationCode":"packages = options.view_as(SetupOptions).jar_packages or []\nbad = [p for p in packages if not os.path.basename(p).endswith('.jar')]\nif bad:\n    raise SystemExit(f'jar_packages must end with .jar: {bad}')","typeGuard":"def is_jar_package(p): return isinstance(p, str) and os.path.basename(p).endswith('.jar')","tryCatchPattern":"try:\n    stager.create_and_stage_job_resources(setup_options)\nexcept RuntimeError as e:\n    if \"jar_packages=' option expects a full path\" in str(e):\n        sys.exit(f'Fix jar_packages entry: {e}')\n    raise","preventionTips":["Validate extensions in your launcher before building PipelineOptions","Keep jar URLs clean (no query strings/whitespace)","Don't mix up jar_packages with extra_package"],"tags":["python","cli","validation","beam"],"backgroundTag":"invalid-cli-argument","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}