{"record":{"id":"cf9a6a3e3a196e69","repo":"grpc/grpc-go","slug":"grpctransport-failed-to-create-connection-to-serv","errorCode":null,"errorMessage":"grpctransport: failed to create connection to server %q: %v","messagePattern":"grpctransport: failed to create connection to server %q: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/xds/clients/grpctransport/grpc_transport.go","lineNumber":137,"sourceCode":"\t\treturn tr, nil\n\t}\n\n\t// Create a new gRPC client/channel for the server with the provided\n\t// credentials, server URI, and a byte codec to send and receive messages.\n\t// Also set a static keepalive configuration that is common across gRPC\n\t// language implementations.\n\tkpCfg := grpc.WithKeepaliveParams(keepalive.ClientParameters{\n\t\tTime:    5 * time.Minute,\n\t\tTimeout: 20 * time.Second,\n\t})\n\tdopts := []grpc.DialOption{kpCfg, grpc.WithCredentialsBundle(config.Credentials), grpc.WithDefaultCallOptions(grpc.ForceCodec(&byteCodec{}))}\n\tnewClientFunc := grpc.NewClient\n\tif config.GRPCNewClient != nil {\n\t\tnewClientFunc = config.GRPCNewClient\n\t}\n\tcc, err := newClientFunc(si.ServerURI, dopts...)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"grpctransport: failed to create connection to server %q: %v\", si.ServerURI, err)\n\t}\n\ttr := &grpcTransport{cc: cc}\n\t// Register a cleanup function that decrements the refs to the gRPC\n\t// transport each time Close() is called to close it and remove from\n\t// transports and connections map if last reference is being released.\n\ttr.cleanup = b.cleanupFunc(si, tr)\n\n\t// Add the newly created connection to the maps to re-use the transport\n\t// channel and track references.\n\tb.connections[si] = cc\n\tb.refs[si] = 1\n\n\tif logger.V(2) {\n\t\tlogger.Infof(\"Created a new transport to the server for ServerIdentifier: %v\", si)\n\t}\n\treturn tr, nil\n}\n","sourceCodeStart":119,"sourceCodeEnd":155,"githubUrl":"https://github.com/grpc/grpc-go/blob/0c51461d27177d997e14c642fe18c11668fc09a3/internal/xds/clients/grpctransport/grpc_transport.go#L119-L155","documentation":"Returned when the underlying gRPC client constructor fails to create a *grpc.ClientConn for the given ServerURI (grpc_transport.go:137). This wraps the raw error from grpc.NewClient (or a custom GRPCNewClient). Note this is a construction-time error, not a connection failure - gRPC dials lazily, so most network errors surface later on the stream.","triggerScenarios":"newClientFunc(si.ServerURI, dopts...) returns a non-nil error. With the default grpc.NewClient this typically means an invalid target syntax; with a custom GRPCNewClient it can be any error from that function.","commonSituations":"ServerURI uses a resolver scheme the build does not support (e.g. missing dns:/// prefix or an unknown scheme); a custom GRPCNewClient rejects the target; credentials bundle is incompatible with the dial options; gRPC version downgrade where NewClient signature differs.","solutions":["Validate the ServerURI format (scheme, authority, port) before Build.","If using a custom GRPCNewClient, test it in isolation against the same target.","Inspect the wrapped error - it names the underlying cause (e.g. 'no resolver registered for scheme').","Ensure the credentials bundle returned a non-nil TransportCredentials and that the gRPC version supports WithCredentialsBundle."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Validate the target syntax before Build:\nif si.ServerURI == \"\" || !looksLikeValidTarget(si.ServerURI) {\n    return fmt.Errorf(\"invalid ServerURI %q\", si.ServerURI)\n}","typeGuard":null,"tryCatchPattern":"tr, err := builder.Build(si)\nif err != nil && strings.Contains(err.Error(), \"failed to create connection to server\") {\n    // inspect wrapped error: invalid scheme, resolver missing, etc.\n}","preventionTips":["Standardize ServerURI format (e.g. dns:///<host>:<port>) across the codebase.","Test custom GRPCNewClient functions in isolation before plugging them in.","Pin the gRPC version to match the WithCredentialsBundle API."],"tags":["grpctransport","grpc","xds","network","configuration"],"backgroundTag":null,"analyzedSha":"0c51461d27177d997e14c642fe18c11668fc09a3","analyzedAt":"2026-08-11T14:49:15.055Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}