{"record":{"id":"3e8121c3242211c5","repo":"apache/beam","slug":"error-in-starting-expansion-service-startservice-w","errorCode":null,"errorMessage":"error in starting expansion service, StartService(): %w","messagePattern":"error in starting expansion service, StartService\\(\\): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"sdks/go/pkg/beam/core/runtime/xlangx/expand.go","lineNumber":218,"sourceCode":"\tjarPath, err := expansionx.GetBeamJar(gradleTarget, core.SdkVersion)\n\tif err != nil {\n\t\treturn nil, \"\", err\n\t}\n\n\tif len(classpath) > 0 {\n\t\tjarPath, err = expansionx.MakeJar(jarPath, classpath)\n\t\tif err != nil {\n\t\t\treturn nil, \"\", err\n\t\t}\n\t}\n\n\tserviceRunner, err := expansionx.NewExpansionServiceRunner(jarPath, \"\")\n\tif err != nil {\n\t\treturn nil, \"\", fmt.Errorf(\"error in  startAutomatedJavaExpansionService(%s,%s): %w\", gradleTarget, classpath, err)\n\t}\n\terr = serviceRunner.StartService()\n\tif err != nil {\n\t\treturn nil, \"\", fmt.Errorf(\"error in starting expansion service, StartService(): %w\", err)\n\t}\n\tstopFunc = serviceRunner.StopService\n\taddress = serviceRunner.Endpoint()\n\treturn stopFunc, address, nil\n}\n\n// QueryAutomatedExpansionService submits an external transform to be expanded by the\n// expansion service and then eagerly materializes the artifacts for staging. The given\n// transform should be the external transform, and the components are any additional\n// components necessary for the pipeline snippet.\n//\n// The address to be queried is determined by the Config field of the HandlerParams after\n// the prefix tag indicating the automated service is in use.\nfunc QueryAutomatedExpansionService(ctx context.Context, p *HandlerParams) (*jobpb.ExpansionResponse, error) {\n\t// Strip auto: tag to get Gradle target\n\ttag, target := parseAddr(p.Config)\n\t// parse classpath namespace if present\n\ttarget, classpath := parseClasspath(target)","sourceCodeStart":200,"sourceCodeEnd":236,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/go/pkg/beam/core/runtime/xlangx/expand.go#L200-L236","documentation":"After the expansion service runner is constructed, StartService() launches it (background JVM process listening on an endpoint). If startup fails — JVM exits, port binding fails, service times out — this error wraps the cause from startAutomatedJavaExpansionService.","triggerScenarios":"QueryAutomatedExpansionService → startAutomatedJavaExpansionService when serviceRunner.StartService() returns non-nil: JVM startup failure, endpoint port already in use, classpath errors in the jar, or startup timeout.","commonSituations":"Port conflicts with other local services, Java version incompatibilities with the expansion jar, slow first-time Gradle builds exceeding startup timeouts, or firewall blocks on the chosen port.","solutions":["Check the wrapped StartService error — often a port conflict; free the port or pick another.","Verify Java version meets the expansion service jar's requirements.","Retry after warm-up: first automated expansion downloads/builds the jar and can time out; pre-build it once.","Run the expansion service manually (java -jar) and connect via a fixed endpoint.","Inspect the expansion service's stderr/stdout logs for JVM classpath errors."],"exampleFix":"// before\nstop, addr, err := xlangx.QueryAutomatedExpansionService(ctx, req, nil, gradleTarget) // port 8097 busy\n// after\n// free the port or run the service yourself:\n// java -jar expansion-service.jar 8098\nres, err := xlangx.Expand(ctx, req, nil, \"localhost:8098\")","handlingStrategy":"retry","validationCode":"conn, err := net.DialTimeout(\"tcp\", \"localhost:8097\", 2*time.Second)\nif err == nil { conn.Close(); return fmt.Errorf(\"port 8097 already in use\") }","typeGuard":null,"tryCatchPattern":"stop, addr, err := xlangx.QueryAutomatedExpansionService(ctx, req, o, target)\nif err != nil {\n\tif errors.Is(err, context.DeadlineExceeded) {\n\t\t// first call may be slow due to gradle warm-up; retry once\n\t}\n\treturn err\n}\ndefer stop()","preventionTips":["Pick a free, non-conflicting port for the expansion service.","Warm up the jar/build once before time-sensitive runs.","Match the JVM version to the expansion service requirements.","Keep a manually-run expansion service as fallback."],"tags":["xlang","expansion-service","jvm","process-start","beam","go"],"backgroundTag":"connection-refused","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T21:17:11.552Z"}