apache/beam · error · RuntimeError

Unable to fetch remote job server jar at

Error message

Unable to fetch remote job server jar at {url}: {e}. Also failed to fetch from Google Maven mirror at {fallback_url}: {fallback_e}. If no Internet access at runtime, stage the jar at {cached_jar}

What it means

local_jar() downloads the job-server jar from a remote URL into a cache directory, with a Google Maven mirror as fallback. If both the primary URL and the mirror fail with URLError, it raises with both underlying errors and suggests manually staging the jar at the cache path. It is a network/availability failure, not a code bug.

Solutions

1. Pre-stage the jar manually: download it on a connected machine and place it at the path given in {cached_jar}; local_jar() will then skip downloading.
2. Restore outbound HTTPS to repo.maven.apache.org and mirror.googleapis.com (proxy settings, firewall rules, DNS).
3. Configure urllib proxy environment variables (https_proxy) so downloads work through your corporate proxy.
4. Use a released Beam version whose jar URL is valid on Maven Central.

Example fix

# before
# rely on runtime download in air-gapped cluster (fails)
# after
curl -o ~/.apache_beam/cache/beam-runners-flink-1.17-job-server.jar \
  https://repo.maven.apache.org/maven2/org/apache/beam/beam-runners-flink-1.17-job-server/.../beam-runners-flink-1.17-job-server-1.17.jar

import urllib.request
for u in [primary_jar_url, mirror_jar_url]:
    try:
        urllib.request.urlopen(u, timeout=10)
        break
    except Exception as e:
        last = e
else:
    print('No network to jar repos; pre-stage the jar in the cache dir')

When it happens

Trigger: Both cls._download_jar_to_cache(url,...) and the mirror fallback raise URLError — no internet access, DNS failure, proxy/firewall blocking repo.maven.apache.org and mirror.googleapis.com, or a bad jar URL.

Common situations: Running Beam in an air-gapped/VPN'd corporate network; CI nodes without outbound HTTPS; transient Maven outages; typo'd or removed jar URL after a version change.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

• Unable to fetch remote job server jar at
• Artifact not found at
• Failed to retrieve secret bytes for secret
• A BigQuery table or a query must be specified
• A cluster_identifier should be Optional[Union[str…

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

Appendix: source

Thrown at sdks/python/apache_beam/utils/subprocess_server.py:578

          os.makedirs(cache_dir)
          # TODO: Clean up this cache according to some policy.
        try:
          cls._download_jar_to_cache(url, cached_jar, user_agent)
        except URLError as e:
          # Try Google Maven mirror as fallback if the original URL is from
          # Maven Central
          if url.startswith(cls.MAVEN_CENTRAL_REPOSITORY):
            fallback_url = url.replace(
                cls.MAVEN_CENTRAL_REPOSITORY, cls.GOOGLE_MAVEN_MIRROR)
            _LOGGER.info(
                'Trying Google Maven mirror fallback: %s' % fallback_url)
            try:
              cls._download_jar_to_cache(fallback_url, cached_jar, user_agent)
              _LOGGER.info(
                  'Successfully downloaded from Google Maven mirror: %s' %
                  fallback_url)
            except URLError as fallback_e:
              raise RuntimeError(
                  f'Unable to fetch remote job server jar at {url}: {e}. '
                  f'Also failed to fetch from Google Maven mirror at '
                  f'{fallback_url}: {fallback_e}. '
                  f'If no Internet access at runtime, stage the jar at '
                  f'{cached_jar}')
          else:
            raise RuntimeError(
                f'Unable to fetch remote job server jar at {url}: {e}. If no '
                f'Internet access at runtime, stage the jar at {cached_jar}')
      return cached_jar

  @classmethod
  @contextlib.contextmanager
  def beam_services(cls, replacements):
    try:
      old = cls._BEAM_SERVICES.replacements
      cls._BEAM_SERVICES.replacements = dict(old, **replacements)
      yield

View on GitHub (pinned to 12126d8942)