{"record":{"id":"d2b358b59861b225","repo":"apache/beam","slug":"the-file-s-cannot-be-found-it-was-specified-in-the-stager","errorCode":null,"errorMessage":"The file %s cannot be found. It was specified in the --experiment='jar_packages=' command line option.","messagePattern":"The file (.+?) cannot be found\\. It was specified in the --experiment='jar_packages=' command line option\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/runners/portability/stager.py","lineNumber":586,"sourceCode":"    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\n    local_packages.extend([\n        FileSystems.join(staging_temp_dir, f)\n        for f in os.listdir(staging_temp_dir)\n    ])\n\n    for package in local_packages:\n      basename = os.path.basename(package)\n      resources.append(Stager._create_file_stage_to_artifact(package, basename))\n\n    return resources\n\n  @staticmethod\n  def _create_extra_packages(","sourceCodeStart":568,"sourceCodeEnd":604,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/runners/portability/stager.py#L568-L604","documentation":"After validating the .jar suffix, _create_jar_packages checks each package exists locally; remote paths are downloaded first. If a non-remote jar is not an existing file, this RuntimeError is raised naming the missing package.","triggerScenarios":"create_job_resources with a jar_packages entry that is not a remote path and os.path.isfile(package) is False.","commonSituations":"Jar built locally but path built on another host (Dataflow/containers don't see your laptop's /home path); deleted jar; typo in path; using a relative path from a different working directory.","solutions":["Pass the absolute path to the jar that exists on the machine launching the job","Host the jar at an https:// URL so Beam downloads it during staging","Rebuild/copy the jar to the driver environment before submission","Verify with `ls -l <jar>` on the submission host"],"exampleFix":"// before\n--experiment=jar_packages=target/my-lib.jar\n// after\n--experiment=jar_packages=/home/user/project/target/my-lib.jar","handlingStrategy":"validation","validationCode":"packages = options.view_as(SetupOptions).jar_packages or []\nmissing = [p for p in packages\n           if not p.startswith(('http://', 'https://', 'gs://'))\n           and not os.path.isfile(p)]\nif missing:\n    raise SystemExit(f'jar_packages files missing: {missing}')","typeGuard":"def jar_exists_or_remote(p):\n    return Stager._is_remote_path(p) or os.path.isfile(p)","tryCatchPattern":"try:\n    stager.create_and_stage_job_resources(setup_options)\nexcept RuntimeError as e:\n    if \"jar_packages=' command line option\" in str(e):\n        sys.exit(f'Jar not found on driver host: {e}')\n    raise","preventionTips":["Ship jars to the submission environment or host them at URLs","Use absolute paths","Add a pre-submit existence check for all local artifacts"],"tags":["python","cli","file-not-found","beam"],"backgroundTag":"file-not-found","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"}