apache/beam · error · ValueError

Unable to parse jar URL

Error message

Unable to parse jar URL "%s". If using a full URL, make sure the scheme is specified. If using a local file path, make sure the file exists; you may have to first build the job server using `./gradlew -Pwith-kafka-streams-runner runners:kafka-streams:job-server:shadowJar`.

What it means

KafkaStreamsRunner's path_to_jar validates the --kafka_streams_job_server_jar option. If the value doesn't exist as a local file, it's treated as a URL — but if URL parsing finds no scheme, the option is neither a valid path nor a valid URL, so it raises ValueError with guidance on building the job server jar.

Solutions

Build the jar: ./gradlew -Pwith-kafka-streams-runner runners:kafka-streams:job-server:shadowJar and pass the produced path.
If it's a URL, include the scheme, e.g. file:///path/to/job-server.jar or https://...
Verify the path with ls/os.path.exists and run from the directory you expect.
Use an absolute path for the jar.

Example fix

// before
--kafka_streams_job_server_jar=runners/kafka-streams/job-server/build/libs/job.jar
// after
--kafka_streams_job_server_jar=/abs/path/beam/runners/kafka-streams/job-server/build/libs/beam-runners-kafka-streams-job-server-2.xx.0-SNAPSHOT.jar

Defensive patterns

Strategy: validation

Validate before calling

import os, urllib.parse
jar = options.kafka_streams_job_server_jar
assert jar and (os.path.exists(jar) or urllib.parse.urlparse(jar).scheme)

Type guard

def jar_resolves(v): return bool(v) and (os.path.exists(v) or bool(urllib.parse.urlparse(v).scheme))

Try / catch

try:
    jar = runner.path_to_jar()
except ValueError as e:
    build_jar_with_gradle()

Prevention

Build the shadowJar before first run
Use absolute paths for local jars
Include the scheme for URL-form jar options

When it happens

Trigger: Passing --kafka_streams_job_server_jar a typo'd path (file doesn't exist) or a path-like string with no scheme and no file at that location, e.g. 'kafka/target/job.jar' that was never built.

Common situations: Forgetting to build the job server shadowJar with Gradle first; running from a pip-installed Beam where the jar isn't bundled; typos or relative paths that don't resolve from the current working directory.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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

Appendix: source

Thrown at sdks/python/apache_beam/runners/portability/kafka_streams_runner.py:99

    if options_str not in JOB_SERVER_CACHE:
      JOB_SERVER_CACHE[options_str] = job_server.StopOnExitJobServer(
          KafkaStreamsJarJobServer(options))
    return JOB_SERVER_CACHE[options_str]


class KafkaStreamsJarJobServer(job_server.JavaJarJobServer):
  def __init__(self, options):
    super().__init__(options)
    kafka_streams_options = options.view_as(
        pipeline_options.KafkaStreamsRunnerOptions)
    self._jar = kafka_streams_options.kafka_streams_job_server_jar

  def path_to_jar(self):
    if self._jar:
      if not os.path.exists(self._jar):
        url = urllib.parse.urlparse(self._jar)
        if not url.scheme:
          raise ValueError(
              'Unable to parse jar URL "%s". If using a full URL, make sure '
              'the scheme is specified. If using a local file path, make sure '
              'the file exists; you may have to first build the job server '
              'using `./gradlew -Pwith-kafka-streams-runner '
              'runners:kafka-streams:job-server:shadowJar`.' % self._jar)
      return self._jar

    # No jar was given, so look for one built from this source tree. The base
    # class would fall back to Maven Central, but the job server is not
    # published for any Beam release, so that download always fails and says
    # nothing useful about why.
    local_jar = subprocess_server.JavaJarServer.path_to_dev_beam_jar(
        ':runners:kafka-streams:job-server:shadowJar')
    if os.path.exists(local_jar):
      return local_jar
    raise RuntimeError(
        'The Kafka Streams runner is experimental and is not part of any '
        'Apache Beam release, so there is no published job server jar to '

View on GitHub (pinned to 12126d8942)