{"record":{"id":"76805e1bc38a8c23","repo":"cilium/cilium","slug":"start-transport-w","errorCode":null,"errorMessage":"start transport: %w","messagePattern":"start transport: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/xds/experimental/client/client.go","lineNumber":208,"sourceCode":"\t\t}\n\t}\n}\n\n// process creates a transport, sends initial requests and spins up two additional goroutines:\n//   - fetchResponses which passes objects from Recv calls onto a queue\n//   - loop which processes responses queued up by fetchResponses goroutine, and\n//     processes requests queued up by calls to Observe method\n//\n// If any of the goroutines fails with non-retryable error, or terminates, it\n// will stop the transport (by cancelling its context) and wait for all\n// goroutines started by it to finish processing.\nfunc (c *XDSClient[ReqT, RespT]) process(parentCtx context.Context, client discoverypb.AggregatedDiscoveryServiceClient) error {\n\tctx, cancel := context.WithCancel(parentCtx)\n\n\ttrans, err := c.xds.transport(ctx, client)\n\tif err != nil {\n\t\tcancel()\n\t\treturn fmt.Errorf(\"start transport: %w\", err)\n\t}\n\n\terrRespCh := make(chan error, 1)\n\tgo c.fetchResponses(ctx, errRespCh, trans)\n\terrLoopCh := make(chan error, 1)\n\tgo c.loop(ctx, errLoopCh, trans)\n\n\tdefer func() {\n\t\tcancel()\n\t\t<-errLoopCh\n\t\t<-errRespCh\n\t}()\n\n\tfor {\n\t\tselect {\n\t\tcase <-ctx.Done():\n\t\t\treturn ctx.Err()\n\t\tcase err, ok := <-errRespCh:","sourceCodeStart":190,"sourceCodeEnd":226,"githubUrl":"https://github.com/cilium/cilium/blob/ac7b90affa4baf0642e6685319d56907b3a73a6d/pkg/xds/experimental/client/client.go#L190-L226","documentation":"The XDSClient's process goroutine wraps any failure from establishing the xDS gRPC transport stream (trans := c.xds.transport(...)) with the prefix 'start transport:'. It means the AggregatedDiscoveryService stream could not be opened, so the client cannot talk to the xDS management server at all and Run returns. The underlying cause (connection refused, TLS failure, RPC error) is preserved via %w.","triggerScenarios":"XDSClient.Run is called and c.xds.transport() fails to create the gRPC bidi stream — e.g. the gRPC channel to the xDS server is in TRANSIENT_FAILURE, the transport builder's initial stream creation returns an error, or the parent context is already canceled before the stream opens.","commonSituations":"xDS server address/port misconfigured (cilium-configmap or --xds flags pointing to wrong host), the xDS management server (or an intermediate proxy) is down, mTLS certificates are missing/expired so the TLS handshake fails, or network policy/firewall blocks the gRPC port.","solutions":["Verify the xDS server address/port configuration the client was built with is reachable (nc/curl the host:port).","Check mTLS/TLS credentials: ensure the CA cert, client cert and key files exist and are valid and match the server's expectations.","Check connectivity from the agent pod/host to the xDS server (network policies, firewall, service endpoints).","Inspect the wrapped error returned to Run; it identifies the concrete transport failure to fix.","If intentional shutdown, this error is expected when the parent context is canceled; treat context.Canceled as benign."],"exampleFix":"// before\ncfg := xdsclient.Config{ TypeURLs: ..., } // server address left default/empty\ncl, _ := xdsclient.NewClient(cfg)\ngo cl.Run(ctx)\n// after\ncfg := xdsclient.Config{ TypeURLs: ... }\n// ensure address matches the running xDS server, e.g.\n// grpc.WithContextDialer to 'xds-server:18000' + valid transport credentials\ncl, err := xdsclient.NewClient(cfg)\nif err != nil { log.Fatal(err) }\ngo cl.Run(ctx)","handlingStrategy":"retry","validationCode":"// before Run: verify reachability of the xDS endpoint\nhost, port := \"xds-server\", 18000\nif conn, err := net.DialTimeout(\"tcp\", net.JoinHostPort(host, strconv.Itoa(port)), 2*time.Second); err != nil {\n\treturn fmt.Errorf(\"xDS server %s:%d unreachable: %w\", host, port, err)\n} else { conn.Close() }","typeGuard":null,"tryCatchPattern":"err := cl.Run(ctx)\nif err != nil && strings.HasPrefix(err.Error(), \"start transport:\") {\n\tlog.Errorf(\"xDS transport failed to start: %v\", errors.Unwrap(err))\n\t// retry with backoff unless ctx canceled\n\tif !errors.Is(err, context.Canceled) { scheduleRestart() }\n}","preventionTips":["Validate the xDS server address/port configuration at startup with a dial check.","Ship and verify TLS/mTLS cert files exist and are not expired before Run.","Prefer retry-with-backoff around Run instead of failing the whole agent.","Keep gRPC keepalive enabled so the channel recovers from transient failures."],"tags":["grpc","xds","network","transport"],"backgroundTag":"grpc-unavailable","analyzedSha":"ac7b90affa4baf0642e6685319d56907b3a73a6d","analyzedAt":"2026-08-31T18:27:15.868Z","schemaVersion":2},"datasetVersion":"2026-08-31T22:30:34.772Z"}