{"record":{"id":"988454f3679b140b","repo":"hyperledger/fabric","slug":"failed-to-create-new-connection","errorCode":null,"errorMessage":"failed to create new connection","messagePattern":"failed to create new connection","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/pkg/comm/config.go","lineNumber":178,"sourceCode":"\t} else {\n\t\tdialOpts = append(dialOpts, grpc.WithTransportCredentials(insecure.NewCredentials()))\n\t}\n\n\treturn dialOpts, nil\n}\n\nfunc (cc ClientConfig) Dial(address string) (*grpc.ClientConn, error) {\n\tdialOpts, err := cc.DialOptions()\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tctx, cancel := context.WithTimeout(context.Background(), cc.DialTimeout)\n\tdefer cancel()\n\n\tconn, err := grpc.DialContext(ctx, address, dialOpts...)\n\tif err != nil {\n\t\treturn nil, errors.Wrap(err, \"failed to create new connection\")\n\t}\n\treturn conn, nil\n}\n\n// Clone clones this ClientConfig\nfunc (cc ClientConfig) Clone() ClientConfig {\n\tshallowClone := cc\n\treturn shallowClone\n}\n\n// SecureOptions defines the TLS security parameters for a GRPCServer or\n// GRPCClient instance.\ntype SecureOptions struct {\n\t// VerifyCertificate, if not nil, is called after normal\n\t// certificate verification by either a TLS client or server.\n\t// If it returns a non-nil error, the handshake is aborted and that error results.\n\tVerifyCertificate func(rawCerts [][]byte, verifiedChains [][]*x509.Certificate) error\n\t// PEM-encoded X509 public key to be used for TLS communication","sourceCodeStart":160,"sourceCodeEnd":196,"githubUrl":"https://github.com/hyperledger/fabric/blob/2736b63f8fd5932511d56fe68b7039d15977f7f6/internal/pkg/comm/config.go#L160-L196","documentation":"Comm.ClientConfig.Dial wraps grpc.DialContext with a dial timeout; when the underlying gRPC dial fails (DNS resolution failure, connection refused, TLS handshake setup, context deadline), it wraps the error with 'failed to create new connection'. The root cause is always embedded in the wrapped error.","triggerScenarios":"Dialing an unreachable/wrong peer address or port; DNS failure for the peer hostname; dial timeout exceeded (ConnectionTimeout too small); TLS config mismatch preventing connection setup.","commonSituations":"Peer container not running or wrong port in config; Kubernetes service DNS names unresolvable from the client; firewalls blocking the gRPC port; certificate hostname mismatches with TLS enabled; slow networks exceeding DialTimeout.","solutions":["Inspect the wrapped cause (errors.Cause / %v of the returned error) — it names the real failure (refused, timeout, DNS, TLS).","Verify the peer address:port is correct and reachable (nc -vz host port).","Increase cc.DialTimeout in ClientConfig if the network is slow.","If TLS is enabled, confirm serverNameOverride and the root CA cert match the peer's certificate.","Ensure the peer process/container is running and the port is exposed."],"exampleFix":"// before\nconn, err := grpc.DialContext(ctx, address, dialOpts...) // default short timeout\n// after\ncc.DialTimeout = 15 * time.Second\nconn, err := comm.NewClientConfig(...).Dial(address) // log errors.Wrap cause, retry transient failures","handlingStrategy":"try-catch","validationCode":"// pre-flight reachability check before Dial\nhost, port, _ := net.SplitHostPort(address)\nif conn, err := net.DialTimeout(\"tcp\", net.JoinHostPort(host, port), 3*time.Second); err != nil {\n    return fmt.Errorf(\"peer %s unreachable: %w\", address, err)\n} else { conn.Close() }","typeGuard":"func isConnFailure(err error) bool {\n    return err != nil && strings.Contains(err.Error(), \"failed to create new connection\")\n}","tryCatchPattern":"conn, err := cc.Dial(address)\nif err != nil {\n    // unwrap the grpc cause\n    return fmt.Errorf(\"dial %s: %v\", address, errors.Unwrap(err))\n    // retry with backoff only for transient causes (timeout, unavailable)\n}","preventionTips":["Always log the unwrapped root cause, not just 'failed to create new connection'","Set a realistic DialTimeout in ClientConfig for your network","Pre-verify peer address/DNS/TLS certs before dialing","Add retry with exponential backoff for transient network causes"],"tags":["grpc","network","connection","fabric"],"backgroundTag":"failed-to-create-connection","analyzedSha":"2736b63f8fd5932511d56fe68b7039d15977f7f6","analyzedAt":"2026-09-04T08:52:36.465Z","contentChangedAt":"2026-09-04T08:52:36.465Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}