{"record":{"id":"7435200bf5bb0640","repo":"apache/beam","slug":"unable-to-connect-to-expansion-service-at-v","errorCode":null,"errorMessage":"unable to connect to expansion service at %v","messagePattern":"unable to connect to expansion service at (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"sdks/go/pkg/beam/core/runtime/xlangx/expand.go","lineNumber":165,"sourceCode":"\t})\n}\n\n// QueryExpansionService submits an external transform to be expanded by the\n// expansion service. The given transform should be the external transform, and\n// the components are any additional components necessary for the pipeline\n// snippet.\n//\n// The address to be queried is determined by the Config field of HandlerParams.\n//\n// This HandlerFunc is exported to simplify building custom handler functions\n// that do end up calling a Beam ExpansionService, either as a fallback or\n// as part of normal flow.\nfunc QueryExpansionService(ctx context.Context, p *HandlerParams) (*jobpb.ExpansionResponse, error) {\n\treq := p.Req\n\t// Setting grpc client\n\tconn, err := grpc.Dial(p.Config, grpc.WithInsecure())\n\tif err != nil {\n\t\terr = errors.Wrapf(err, \"unable to connect to expansion service at %v\", p.Config)\n\t\treturn nil, errors.WithContextf(err, \"expanding transform with ExpansionRequest: %v\", req)\n\t}\n\tdefer conn.Close()\n\tclient := jobpb.NewExpansionServiceClient(conn)\n\n\t// Handling ExpansionResponse\n\tretryOpts := []retry.Option{\n\t\tretry.Attempts(maxRetries),\n\t\tretry.DelayType(func(n uint, err error, config *retry.Config) time.Duration {\n\t\t\tif n == 0 {\n\t\t\t\treturn time.Second\n\t\t\t}\n\t\t\treturn retry.BackOffDelay(n, err, config)\n\t\t}),\n\t}\n\tvar res *jobpb.ExpansionResponse\n\terr = retry.Do(func() error {\n\t\tres, err = client.Expand(ctx, req)","sourceCodeStart":147,"sourceCodeEnd":183,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/go/pkg/beam/core/runtime/xlangx/expand.go#L147-L183","documentation":"Raised in xlangx.QueryExpansionService when grpc.Dial cannot establish a connection to the expansion service address in p.Config. It indicates the gRPC client could not even be created/dialed for the ExpansionRequest, and the error is annotated with the request for context.","triggerScenarios":"Calling QueryPythonExpansionService or QueryAutomatedExpansionService with an expansion service address that is malformed, unreachable, or refused the gRPC dial.","commonSituations":"Expansion service not started or crashed before use; wrong host/port passed via expansion service config; firewall or DNS issues; specifying an invalid URL such as missing port or scheme.","solutions":["Verify the expansion service address is correct and reachable (host:port), e.g. with grpcurl or nc","Start the expansion service and confirm it is listening on the configured port","Check network/firewall/DNS rules between the Go pipeline and the service host","If relying on QueryAutomatedExpansionService, confirm the service JAR/download succeeded and the port is free"],"exampleFix":"// before\nxlangx.QueryPythonExpansionService(ctx, req, \"localhost:9999\") // nothing listening\n// after\n// start: python -m apache_beam.runners.portability.expansion_service_main --port 5555\nxlangx.QueryPythonExpansionService(ctx, req, \"localhost:5555\")","handlingStrategy":"validation","validationCode":"host, port, err := net.SplitHostPort(addr)\nif err != nil {\n    return fmt.Errorf(\"bad expansion service address %q: %w\", addr, err)\n}\nif conn, err := net.DialTimeout(\"tcp\", net.JoinHostPort(host, port), 2*time.Second); err != nil {\n    return fmt.Errorf(\"expansion service not reachable at %s: %w\", addr, err)\n} else {\n    conn.Close()\n}","typeGuard":null,"tryCatchPattern":"res, err := xlangx.QueryExpansionService(ctx, params)\nif err != nil {\n    return fmt.Errorf(\"expansion service %s unreachable: %w\", params.Config, err)\n}","preventionTips":["Health-check the expansion service port before running the pipeline","Centralize the expansion service address in config and validate host:port format","Ensure the service is started before launching cross-language pipelines"],"tags":["network","grpc","cross-language","connection"],"backgroundTag":"connection-refused","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"}