apache/beam · error · IllegalArgumentException

Either option TransformServiceAddress or option TransformSer

Error message

Either option TransformServiceAddress or option TransformServiceBeamVersion should be provided to override a transform using the transform service

What it means

To upgrade a transform via the transform service, TransformUpgrader needs either an external TransformServiceAddress or a TransformServiceBeamVersion from which a local service can be started. If neither option is set, it cannot obtain a service endpoint and throws IllegalArgumentException.

Source

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

    String serviceAddress;
    TransformServiceLauncher service = null;

    ExternalTranslationOptions externalTranslationOptions =
        options.as(ExternalTranslationOptions.class);
    if (externalTranslationOptions.getTransformServiceAddress() != null) {
      serviceAddress = externalTranslationOptions.getTransformServiceAddress();
    } else if (externalTranslationOptions.getTransformServiceBeamVersion() != null) {
      String projectName = UUID.randomUUID().toString();
      int port = findAvailablePort();
      service = TransformServiceLauncher.forProject(projectName, port, null);
      service.setBeamVersion(externalTranslationOptions.getTransformServiceBeamVersion());

      // Starting the transform service.
      service.start();
      service.waitTillUp(-1);
      serviceAddress = "localhost:" + Integer.toString(port);
    } else {
      throw new IllegalArgumentException(
          "Either option TransformServiceAddress or option TransformServiceBeamVersion should be "
              + "provided to override a transform using the transform service");
    }

    Endpoints.ApiServiceDescriptor expansionServiceEndpoint =
        Endpoints.ApiServiceDescriptor.newBuilder().setUrl(serviceAddress).build();

    for (String transformId : transformsToOverride) {
      pipeline =
          updateTransformViaTransformService(
              pipeline, transformId, expansionServiceEndpoint, options);
    }

    if (service != null) {
      service.shutdown();
    }

    return pipeline;

View on GitHub (pinned to 12126d8942)

Solutions

1. Set the TransformServiceAddress pipeline option to a running transform service endpoint
2. Set TransformServiceBeamVersion so a local transform service can be started for that version
3. Remove the transformsToOverride option if transform-service upgrading isn't intended

Example fix

// before
PipelineOptions options = ...; // no transform service options set
// after
options.as(TransformUpgraderOptions.class).setTransformServiceBeamVersion("2.60.0");
// or: setTransformServiceAddress("localhost:12345");

TransformUpgraderOptions opts = options.as(TransformUpgraderOptions.class);
if (opts.getTransformsToOverride() != null && !opts.getTransformsToOverride().isEmpty()
    && opts.getTransformServiceAddress() == null
    && opts.getTransformServiceBeamVersion() == null) {
  throw new IllegalStateException(
      "Set TransformServiceAddress or TransformServiceBeamVersion to use transformsToOverride");
}

try { pipeline.run(); } catch (IllegalArgumentException e) {
  if (e.getMessage().contains("TransformServiceAddress")) { /* set one of the two options */ }
  else throw e;
}

When it happens

Trigger: Setting transformsToOverride without --transformServiceAddress and without --transformServiceBeamVersion when calling upgradeTransformsViaTransformService.

Common situations: Forgetting to configure the expansion/transform service address in runner options; intentionally relying on the bundled service but not specifying the Beam version to launch it.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• cannot call getPipelineOptions() in a null context
• Failed to convert PipelineOptions to JSON
• Could not override the transforms with URNs
• A list of URNs for overriding transforms was provided but th
• Illegal access to pipeline after visitor traversal was compl

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