{"record":{"id":"780e74f011d166df","repo":"apache/beam","slug":"expansion-service-error-s-transformupgrader","errorCode":null,"errorMessage":"expansion service error: %s","messagePattern":"expansion service error: (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/util/construction/TransformUpgrader.java","lineNumber":266,"sourceCode":"      // TransformService uses a compatible schema.\n      optionsClone\n          .as(StreamingOptions.class)\n          .setUpdateCompatibilityVersion(ReleaseInfo.getReleaseInfo().getSdkVersion());\n    }\n    ExpansionApi.ExpansionRequest request =\n        requestBuilder\n            .setComponents(runnerAPIpipeline.getComponents())\n            .setTransform(ptransformBuilder.build())\n            .setNamespace(UPGRADE_NAMESPACE)\n            .setPipelineOptions(PipelineOptionsTranslation.toProto(optionsClone))\n            .addAllRequirements(runnerAPIpipeline.getRequirementsList())\n            .build();\n\n    ExpansionApi.ExpansionResponse response =\n        clientFactory.getExpansionServiceClient(transformServiceEndpoint).expand(request);\n\n    if (!Strings.isNullOrEmpty(response.getError())) {\n      throw new RuntimeException(String.format(\"expansion service error: %s\", response.getError()));\n    }\n\n    Map<String, RunnerApi.Environment> newEnvironmentsWithDependencies =\n        response.getComponents().getEnvironmentsMap().entrySet().stream()\n            .filter(\n                kv ->\n                    !runnerAPIpipeline.getComponents().getEnvironmentsMap().containsKey(kv.getKey())\n                        && kv.getValue().getDependenciesCount() != 0)\n            .collect(Collectors.toMap(Map.Entry::getKey, Map.Entry::getValue));\n\n    RunnerApi.Components expandedComponents =\n        response.getComponents().toBuilder()\n            .putAllEnvironments(\n                External.ExpandableTransform.resolveArtifacts(\n                    newEnvironmentsWithDependencies, transformServiceEndpoint))\n            .build();\n    RunnerApi.PTransform expandedTransform = response.getTransform();\n","sourceCodeStart":248,"sourceCodeEnd":284,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/util/construction/TransformUpgrader.java#L248-L284","documentation":"After sending an expansion request to the transform service, TransformUpgrader propagates any error reported in the ExpansionResponse by wrapping it in a RuntimeException with the 'expansion service error:' prefix. This surfaces server-side failures (bad config row, unknown URN, internal service error) to the pipeline author.","triggerScenarios":"The transform service fails to expand/upgrade a transform: unknown schema-transform URN, invalid configuration row, incompatible Beam version, or an internal exception inside the service.","commonSituations":"Wrong URN or malformed config row for a schema transform; transform service of a different Beam version than the SDK; the service-side transform throwing during expansion.","solutions":["Read the embedded response error text in the message — it contains the service's actual failure reason","Verify the transform URN and config row schema match what the service supports","Run the transform service with a Beam version matching your SDK, and check the service logs"],"exampleFix":"// before\n// request built with wrong config row schema\nRow config = Row.withSchema(wrongSchema).addValues(...).build();\n// after\nRow config = Row.withSchema(serviceSupportedSchema).addValues(...).build(); // matches service expectations","handlingStrategy":"retry","validationCode":"// Pre-validate the config row schema against the transform's advertised schema before expansion:\nSchema expected = discoverTransformSchema(urn, serviceAddress); // via expansion service discovery\nif (!config.getSchema().equals(expected)) {\n  throw new IllegalStateException(\"Config row schema mismatch for URN \" + urn);\n}","typeGuard":null,"tryCatchPattern":"try { pipeline.run(); } catch (RuntimeException e) {\n  if (e.getMessage() != null && e.getMessage().startsWith(\"expansion service error:\")) {\n    log.error(\"Transform service failed: {}\", e.getMessage());\n    // fix URN/config or restart matching-version service, then retry\n  } else throw e;\n}","preventionTips":["Read the embedded service error — it names the root cause","Match transform service Beam version with your SDK version","Validate schema-transform URNs and config rows before submission","Check transform service logs for the server-side stack trace"],"tags":["java","beam","expansion-service","remote-error"],"backgroundTag":"api-error-response","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"}