{"record":{"id":"e58b442bbd5817ca","repo":"apache/beam","slug":"expansion-service-error-s","errorCode":null,"errorMessage":"expansion service error: %s","messagePattern":"expansion service error: (.+?)","errorType":"exception","errorClass":"java.lang.RuntimeException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/util/construction/External.java","lineNumber":284,"sourceCode":"                          return components.registerCoder(kv.getValue());\n                        } catch (IOException e) {\n                          throw new RuntimeException(e);\n                        }\n                      })));\n      RunnerApi.Components originalComponents = components.toComponents();\n      ExpansionApi.ExpansionRequest request =\n          requestBuilder\n              .setComponents(originalComponents)\n              .setTransform(ptransformBuilder.build())\n              .setNamespace(getNamespace())\n              .setPipelineOptions(PipelineOptionsTranslation.toProto(p.getOptions()))\n              .build();\n\n      ExpansionApi.ExpansionResponse response =\n          clientFactory.getExpansionServiceClient(endpoint).expand(request);\n\n      if (!Strings.isNullOrEmpty(response.getError())) {\n        throw new RuntimeException(\n            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                      !originalComponents.getEnvironmentsMap().containsKey(kv.getKey())\n                          && kv.getValue().getDependenciesCount() != 0)\n              .collect(Collectors.toMap(Map.Entry::getKey, Map.Entry::getValue));\n\n      expandedComponents =\n          response.getComponents().toBuilder()\n              .putAllEnvironments(resolveArtifacts(newEnvironmentsWithDependencies, endpoint))\n              .build();\n      expandedTransform = response.getTransform();\n      expandedRequirements = response.getRequirementsList();\n","sourceCodeStart":266,"sourceCodeEnd":302,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/util/construction/External.java#L266-L302","documentation":"External.expand() sends a transform to a Beam expansion service over gRPC. When the response carries a non-empty error string, the service rejected the expansion request and this RuntimeException wraps and re-raises that error message. It indicates the expansion service failed to expand the transform (e.g. unknown URN, missing dependencies, service-side exception).","triggerScenarios":"Calling External.expand() (or Beam.expansion of a cross-language transform) against an expansion service endpoint that returns ExpansionResponse.error, e.g. wrong service port, transform URN the service does not support, or missing jar/dependency on the service side.","commonSituations":"Misconfigured expansion service address in PipelineOptions; cross-language transform (e.g. Kafka/SQL) whose service version doesn't match the SDK; expansion service crashed or lacks the requested transform's classpath entries.","solutions":["Read the embedded response.getError() text in the exception message — it names the service-side cause; fix that specific issue first.","Verify the expansion service endpoint (host:port) and that the service is running and reachable.","Ensure the expansion service was started with the jar/classpath containing the requested transform.","Align SDK and expansion service versions; restart the expansion service to pick up new transforms."],"exampleFix":"// before: wrong/missing expansion service\nto.apply(External.of(\"my:transform:v1\", payload, \"localhost:0\"));\n// after: start a real service with the right classpath and use that endpoint\njava -jar beam-sdks-java-expansion-service.jar --classpath deps.jar --port 4444\ntransform.apply(External.of(\"my:transform:v1\", payload, \"localhost:4444\"));","handlingStrategy":"try-catch","validationCode":"// check endpoint reachability before expand\ntry (Socket s = new Socket(host, port)) { /* ok */ } catch (IOException e) { throw new IllegalStateException(\"expansion service unreachable: \" + endpoint, e); }","typeGuard":"boolean isEndpointSet(String endpoint) { return endpoint != null && endpoint.matches(\".+\\\\d+\") && endpoint.contains(\":\"); }","tryCatchPattern":"try { expanded = External.of(urn, payload, endpoint).expand(input); } catch (RuntimeException e) { if (e.getMessage().startsWith(\"expansion service error:\")) { /* log embedded service error, fail pipeline with clear message */ } throw e; }","preventionTips":["Pin and health-check the expansion service endpoint before pipeline launch","Keep expansion service and SDK versions aligned","Start the service with the classpath containing every transform you expand"],"tags":["java","grpc","cross-language","expansion-service"],"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"}