{"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/03255a9237b6eb32710f6bc4f2de9a675b99fe36/internal/xds/clients/grpctransport/grpc_transport.go#L119-L155","documentation":"After all validations pass, Build calls the gRPC new-client function (grpc.NewClient by default, or a custom GRPCNewClient) with the server URI and dial options including the credentials bundle and keepalive params (grpc_transport.go:135-137). If that call returns an error, it is wrapped with the server URI. This is a connection-creation failure, not a connection-establishment failure — grpc.NewClient is lazy, so most errors here come from invalid dial options or a custom client function.","triggerScenarios":"grpc.NewClient (or a custom GRPCNewClient) returns a non-nil error — typically because a DialOption is invalid (e.g. conflicting credentials), the target URI is malformed in a way the resolver rejects immediately, or a custom new-client function has its own precondition that failed.","commonSituations":"The credentials bundle is incompatible with the target scheme; a custom GRPCNewClient performs eager validation or dialing and the server is unreachable; the ServerURI uses a scheme/resolver that errors at construction; environment (proxy) settings interfere with name resolution at client creation.","solutions":["Inspect the wrapped error (%v) — it distinguishes option errors from URI/resolver errors from custom-client errors.","If using a custom GRPCNewClient, test it in isolation with the same target and options.","Verify the ServerURI scheme (dns:///, xds:///, etc.) is supported and well-formed.","Confirm the credentials bundle is compatible with the transport; remove conflicting DialOptions.","For transient network issues inside a custom client, consider retrying Build after a backoff."],"exampleFix":"// before:\n//   builder with a custom GRPCNewClient that dials eagerly and fails\n// after:\n//   test the custom client separately:\n//   cc, err := myClientFunc(\"dns:///xds:443\", dopts...)\n//   if err != nil { log.Printf(\"dial option error: %v\", err) }\n//   // or simplify by using the default grpc.NewClient (GRPCNewClient = nil)","handlingStrategy":"try-catch","validationCode":"// If using a custom GRPCNewClient, sanity-check the target first.\nfunc validateTarget(uri string) error {\n    if uri == \"\" { return errors.New(\"empty target\") }\n    // ensure the scheme is recognized by the gRPC resolver registry\n    return nil\n}","typeGuard":null,"tryCatchPattern":"tr, err := builder.Build(si)\nif err != nil {\n    if strings.Contains(err.Error(), \"failed to create connection\") {\n        // inspect wrapped cause; retry transient failures after backoff\n        return fmt.Errorf(\"transport build failed for %q: %w\", si.ServerURI, err)\n    }\n    return err\n}","preventionTips":["Test custom GRPCNewClient implementations in isolation before wiring them into Config.","Verify the ServerURI scheme is supported by the resolver registry.","Inspect the wrapped error to separate option errors from network errors before retrying."],"tags":["xds","grpctransport","network","grpc","connection"],"analyzedSha":"03255a9237b6eb32710f6bc4f2de9a675b99fe36","analyzedAt":"2026-08-07T00:29:34.215Z","schemaVersion":2},"datasetVersion":"2026-08-07T03:17:09.362Z"}