{"record":{"id":"1a4f8728f2d694cf","repo":"grpc/grpc-go","slug":"xds-failed-to-create-transport-for-server-config","errorCode":null,"errorMessage":"xds: failed to create transport for server config %v: %v","messagePattern":"xds: failed to create transport for server config (.+?): (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"internal/xds/clients/xdsclient/xdsclient.go","lineNumber":291,"sourceCode":"\n\t// Use an existing channel, if one exists for this server config.\n\tif st, ok := c.xdsActiveChannels[*serverConfig]; ok {\n\t\tif c.logger.V(2) {\n\t\t\tc.logger.Infof(\"Reusing an existing xdsChannel for server config %q\", serverConfig)\n\t\t}\n\t\tinitLocked(st)\n\t\treturn st.channel, c.releaseChannel(serverConfig, st, deInitLocked), nil\n\t}\n\n\tif c.logger.V(2) {\n\t\tc.logger.Infof(\"Creating a new xdsChannel for server config %q\", serverConfig)\n\t}\n\n\t// Create a new transport and create a new xdsChannel, and add it to the\n\t// map of xdsChannels.\n\ttr, err := c.transportBuilder.Build(serverConfig.ServerIdentifier)\n\tif err != nil {\n\t\treturn nil, func() {}, fmt.Errorf(\"xds: failed to create transport for server config %v: %v\", serverConfig, err)\n\t}\n\tstate := &channelState{\n\t\tparent:                c,\n\t\tserverConfig:          serverConfig,\n\t\tinterestedAuthorities: make(map[*authority]bool),\n\t}\n\tchannel, err := newXDSChannel(xdsChannelOpts{\n\t\ttransport:          tr,\n\t\tserverConfig:       serverConfig,\n\t\tclientConfig:       c.config,\n\t\teventHandler:       state,\n\t\tbackoff:            c.backoff,\n\t\twatchExpiryTimeout: c.watchExpiryTimeout,\n\t\tlogPrefix:          clientPrefix(c),\n\t})\n\tif err != nil {\n\t\treturn nil, func() {}, fmt.Errorf(\"xds: failed to create a new channel for server config %v: %v\", serverConfig, err)\n\t}","sourceCodeStart":273,"sourceCodeEnd":309,"githubUrl":"https://github.com/grpc/grpc-go/blob/0c51461d27177d997e14c642fe18c11668fc09a3/internal/xds/clients/xdsclient/xdsclient.go#L273-L309","documentation":"The xDS client's TransportBuilder.Build returned an error when attempting to create a transport (network connection) to the xDS management server identified by the given ServerConfig. This wraps the underlying Build error with the server config for diagnostics, and means no ADS (Aggregated Discovery Service) stream can be established to that server, blocking all resource discovery.","triggerScenarios":"Called inside getOrCreateChannel (xdsclient.go:289) when no existing channel matches the server config — typically on the first resource watch or after all channels for a server have been released. The TransportBuilder.Build(serverConfig.ServerIdentifier) call returns a non-nil error (e.g. dial failure, TLS handshake error, unsupported credential type).","commonSituations":"xDS server URI is unresolvable or points to a wrong port; TLS certificate is expired, self-signed, or from an untrusted CA; firewall or network policy blocks the outbound connection; custom TransportBuilder returns an error due to unsupported ServerIdentifier.Extensions credential configuration; server temporarily down during initial connection attempt.","solutions":["Verify the xDS server URI includes host and port and is network-reachable (e.g. test with 'nc -zv host 443')","Check TLS certificate validity and ensure ServerIdentifier.Extensions carries the correct credentials for the TransportBuilder","Inspect the wrapped error in the log — it contains the specific Build failure (DNS resolution, TLS handshake, dial timeout, etc.)","If using a custom TransportBuilder, ensure Build returns (non-nil Transport, nil) for a valid ServerIdentifier","Confirm the xDS management server process is running and accepting connections"],"exampleFix":"// before — unreachable server URI, no port\nconfig.Servers = []xdsclient.ServerConfig{{\n    ServerIdentifier: clients.ServerIdentifier{ServerURI: \"xds-mgmt\"},\n}}\n\n// after — fully qualified URI with port\nconfig.Servers = []xdsclient.ServerConfig{{\n    ServerIdentifier: clients.ServerIdentifier{\n        ServerURI:  \"xds-mgmt.example.com:443\",\n        Extensions: tlsCreds,\n    },\n}}","handlingStrategy":"validation","validationCode":"// Validate server reachability before creating the xDS client.\nfor _, sc := range config.Servers {\n    conn, err := net.DialTimeout(\"tcp\", sc.ServerIdentifier.ServerURI, 5*time.Second)\n    if err != nil {\n        return fmt.Errorf(\"xDS server %s is unreachable: %w\", sc.ServerIdentifier.ServerURI, err)\n    }\n    conn.Close()\n}","typeGuard":null,"tryCatchPattern":"client, err := xdsclient.New(config)\nif err != nil {\n    if strings.Contains(err.Error(), \"failed to create transport\") {\n        // Transport creation failed — inspect wrapped error for network/TLS details.\n        // The xDS client may still be usable if other servers in the list succeed.\n        log.Printf(\"xDS transport creation failed for server: %v\", err)\n    }\n    return err\n}","preventionTips":["Validate xDS server reachability in startup/bootstrap health checks","Use short connection timeouts in the TransportBuilder so failures surface quickly","Monitor the grpc.xds_client.connected metric to detect transport creation failures early","Configure multiple xDS servers for failover so a single unreachable server does not block the client"],"tags":["xds","network","transport","configuration"],"backgroundTag":null,"analyzedSha":"0c51461d27177d997e14c642fe18c11668fc09a3","analyzedAt":"2026-08-11T14:49:15.055Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}