{"record":{"id":"f815e4acf50d75fd","repo":"apache/beam","slug":"either-option-transformserviceaddress-or-option","errorCode":null,"errorMessage":"Either option TransformServiceAddress or option TransformServiceBeamVersion should be provided to override a transform using the transform service","messagePattern":"Either option TransformServiceAddress or option TransformServiceBeamVersion should be provided to override a transform using the transform service","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/util/construction/TransformUpgrader.java","lineNumber":167,"sourceCode":"    String serviceAddress;\n    TransformServiceLauncher service = null;\n\n    ExternalTranslationOptions externalTranslationOptions =\n        options.as(ExternalTranslationOptions.class);\n    if (externalTranslationOptions.getTransformServiceAddress() != null) {\n      serviceAddress = externalTranslationOptions.getTransformServiceAddress();\n    } else if (externalTranslationOptions.getTransformServiceBeamVersion() != null) {\n      String projectName = UUID.randomUUID().toString();\n      int port = findAvailablePort();\n      service = TransformServiceLauncher.forProject(projectName, port, null);\n      service.setBeamVersion(externalTranslationOptions.getTransformServiceBeamVersion());\n\n      // Starting the transform service.\n      service.start();\n      service.waitTillUp(-1);\n      serviceAddress = \"localhost:\" + Integer.toString(port);\n    } else {\n      throw new IllegalArgumentException(\n          \"Either option TransformServiceAddress or option TransformServiceBeamVersion should be \"\n              + \"provided to override a transform using the transform service\");\n    }\n\n    Endpoints.ApiServiceDescriptor expansionServiceEndpoint =\n        Endpoints.ApiServiceDescriptor.newBuilder().setUrl(serviceAddress).build();\n\n    for (String transformId : transformsToOverride) {\n      pipeline =\n          updateTransformViaTransformService(\n              pipeline, transformId, expansionServiceEndpoint, options);\n    }\n\n    if (service != null) {\n      service.shutdown();\n    }\n\n    return pipeline;","sourceCodeStart":149,"sourceCodeEnd":185,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/util/construction/TransformUpgrader.java#L149-L185","documentation":"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.","triggerScenarios":"Setting transformsToOverride without --transformServiceAddress and without --transformServiceBeamVersion when calling upgradeTransformsViaTransformService.","commonSituations":"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.","solutions":["Set the TransformServiceAddress pipeline option to a running transform service endpoint","Set TransformServiceBeamVersion so a local transform service can be started for that version","Remove the transformsToOverride option if transform-service upgrading isn't intended"],"exampleFix":"// before\nPipelineOptions options = ...; // no transform service options set\n// after\noptions.as(TransformUpgraderOptions.class).setTransformServiceBeamVersion(\"2.60.0\");\n// or: setTransformServiceAddress(\"localhost:12345\");","handlingStrategy":"validation","validationCode":"TransformUpgraderOptions opts = options.as(TransformUpgraderOptions.class);\nif (opts.getTransformsToOverride() != null && !opts.getTransformsToOverride().isEmpty()\n    && opts.getTransformServiceAddress() == null\n    && opts.getTransformServiceBeamVersion() == null) {\n  throw new IllegalStateException(\n      \"Set TransformServiceAddress or TransformServiceBeamVersion to use transformsToOverride\");\n}","typeGuard":null,"tryCatchPattern":"try { pipeline.run(); } catch (IllegalArgumentException e) {\n  if (e.getMessage().contains(\"TransformServiceAddress\")) { /* set one of the two options */ }\n  else throw e;\n}","preventionTips":["Always configure the transform service address when overriding transforms","Or pin TransformServiceBeamVersion to launch a matching local service"],"tags":["java","beam","pipeline-options","transform-service"],"backgroundTag":"missing-required-config-field","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}