apache/beam · error · RuntimeError

Unable to fetch remote job server jar at

Error message

Unable to fetch remote job server jar at {url}: {e}. If no Internet access at runtime, stage the jar at {cached_jar}

What it means

Same download path as the dual-failure variant, but here no fallback URL is available (no mirror configured), so the initial URLError alone triggers this error with guidance to stage the jar locally at the cache path. Indicates the remote job-server jar could not be fetched.

Solutions

1. Download the jar manually and place it exactly at the cached_jar path from the message; the method returns it without fetching.
2. Fix network access / proxy env (https_proxy, https_proxy credentials) and retry.
3. Verify the jar URL resolves (curl -I the URL in the message) and use a Beam version that exists on Maven Central.
4. Point the runner at a locally supplied jar instead of relying on local_jar().

Example fix

# before
# pipeline in offline environment attempts download -> URLError
# after
export https_proxy=http://proxy.corp:8080
# or stage the jar:
mkdir -p ~/.apache_beam/cache && cp beam-runners-*.jar ~/.apache_beam/cache/<expected-name>.jar

import urllib.request
try:
    urllib.request.urlopen(jar_url, timeout=10)
except Exception as e:
    print(f'Cannot reach {jar_url}: {e}; stage jar at cache path manually')

When it happens

Trigger: cls._download_jar_to_cache(url, cached_jar, user_agent) raises URLError and no fallback mirror exists — offline machine, DNS failure, HTTP 404 for the jar, or proxy blocking the request.

Common situations: Air-gapped deployments; corporate proxies stripping HTTPS; using a very new/old Beam version whose jar isn't on Maven; temporary Maven Central outages.

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/636dcdaee2ee6aac. Report an issue: GitHub.

Appendix: source

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

          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
    finally:
      cls._BEAM_SERVICES.replacements = old

  @classmethod
  def make_classpath_jar(cls, main_jar, extra_jars, cache_dir=None):
    if cache_dir is None:
      cache_dir = cls.JAR_CACHE

View on GitHub (pinned to 12126d8942)