apache/beam · error · java.lang.UnsupportedOperationException

unsupported Java version

Error message

unsupported Java version: %s

What it means

Environments.JavaVersion.forSpecificationStrict maps a Java specification version string (e.g. "1.8", "11") to the JavaVersion enum, and throws UnsupportedOperationException when the string matches no known version. It guards that only Java versions Beam has Docker images for are used in portable environments.

Solutions

1. Use a supported specification string exactly (e.g. "1.8", "11") matching one of the enum values
2. Upgrade Apache Beam to a release whose JavaVersion enum includes your version
3. Build and point to a custom SDK harness container image if you need an unsupported Java version

Example fix

// before
options.setJavaVersion("1.8.0_292");
// after
options.setJavaVersion("1.8"); // or "11", a value in Environments.JavaVersion

boolean supported = Arrays.stream(Environments.JavaVersion.values())
    .anyMatch(v -> v.specification.equals(requestedJavaSpec));
if (!supported) { /* use a supported spec or upgrade Beam */ }

try { ver = Environments.JavaVersion.forSpecificationStrict(spec); } catch (UnsupportedOperationException e) { ver = Environments.JavaVersion.JAVA_8; }

When it happens

Trigger: Setting PortablePipelineOptions.sdkHarnessContainerImageOptions / java version to a string not in the enum (e.g. "17" or "21" on an older Beam version, or a misspelled/full version like "1.8.0_292").

Common situations: Upgrading the JVM to a newer LTS than the Beam release supports; passing a full java.version string instead of the specification; typos in configuration.

Related errors

• Environment option ' ' is incompatible with environment…
• Environment option ' ' must be set for process environment.
• Java is not correctly installed in JAVA_HOME=
• Java must be installed on this system to use this…
• No proto encoding for PaneInfoCoder, always part of…

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

Appendix: source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/util/construction/Environments.java:171

        LOG.warn(
            "Java8 support is now deprecated and targeted for removal for Beam 3. Falling back to: {}",
            fallback.specification);
      } else {
        LOG.warn(
            "Unsupported Java version: {}, falling back to: {}",
            specification,
            fallback.specification);
      }
      return fallback;
    }

    public static JavaVersion forSpecificationStrict(String specification) {
      for (JavaVersion ver : JavaVersion.values()) {
        if (ver.specification.equals(specification)) {
          return ver;
        }
      }
      throw new UnsupportedOperationException(
          String.format("unsupported Java version: %s", specification));
    }
  }

  /* For development, use the container build by the current user to ensure that the SDK harness and
   * the SDK agree on how they should interact. This should be changed to a version-specific
   * container during a release.
   *
   * See https://beam.apache.org/contribute/docker-images/ for more information on how to build a
   * container.
   */

  @VisibleForTesting
  static final String JAVA_SDK_HARNESS_CONTAINER_URL = getDefaultJavaSdkHarnessContainerUrl();

  public static final Environment JAVA_SDK_HARNESS_ENVIRONMENT =
      createDockerEnvironment(JAVA_SDK_HARNESS_CONTAINER_URL);

View on GitHub (pinned to 12126d8942)