{"record":{"id":"765af5bc2f1a75ce","repo":"hyperledger/fabric","slug":"failed-to-create-new-connection-w","errorCode":null,"errorMessage":"failed to create new connection: %w","messagePattern":"failed to create new connection: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"internal/pkg/gateway/endpoint.go","lineNumber":135,"sourceCode":"\t\t},\n\t\tDialTimeout:  ef.timeout,\n\t\tAsyncConnect: true,\n\t}\n\tdialOpts, err := config.DialOptions()\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tctx, cancel := context.WithTimeout(context.Background(), ef.timeout)\n\tdefer cancel()\n\n\tdialer := ef.dialer\n\tif dialer == nil {\n\t\tdialer = grpc.DialContext\n\t}\n\tconn, err := dialer(ctx, address, dialOpts...)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to create new connection: %w\", err)\n\t}\n\treturn conn, nil\n}\n","sourceCodeStart":117,"sourceCodeEnd":139,"githubUrl":"https://github.com/hyperledger/fabric/blob/2736b63f8fd5932511d56fe68b7039d15977f7f6/internal/pkg/gateway/endpoint.go#L117-L139","documentation":"This error is returned by the Fabric Gateway client when establishing a gRPC connection to a peer or orderer endpoint fails. It wraps the underlying gRPC dial error (newConnection in internal/pkg/gateway/endpoint.go:135), so the root cause (DNS, TLS, timeout) is in the wrapped error. It indicates the client could not reach or complete the handshake with the target node.","triggerScenarios":"Any call that creates an endorser or orderer connection (newEndorser, newOrderer) where ef.dialer (or grpc.DialContext) returns an error for the given address and dial options — e.g. DNS resolution failure, TCP connect refused, TLS handshake failure, or context deadline exceeded.","commonSituations":"Wrong peer hostname/port in connection profile; peer not running or unreachable from the client network; missing or incorrect TLS CA certificates so the handshake fails; Kubernetes/Docker DNS names not resolvable from outside the network; firewall blocking the port.","solutions":["Inspect the wrapped error (%w) to identify the root cause: DNS, connection refused, TLS, or timeout.","Verify the peer/orderer address and port in the connection profile or endpoint config are correct and reachable (test with nc/openssl s_client).","Check TLS settings: ensure the correct CA certificate, server name override, and client key/cert are configured.","If behind NAT/Docker, expose the node's port or use a resolvable hostname instead of the internal service name.","Retry with a longer context deadline if the failure is due to slow network/dial timeout."],"exampleFix":"// before\nconn, err := grpc.DialContext(ctx, \"peer0.org1:7051\", dialOpts...)\nif err != nil {\n    return nil, fmt.Errorf(\"failed to create new connection: %w\", err)\n}\n// after\n// ensure correct address and TLS creds:\ncertPool := x509.NewCertPool()\ncertPool.AppendCertsFromPEM(tlsCACert)\ndialOpts = append(dialOpts,\n    grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{\n        RootCAs:            certPool,\n        ServerNameOverride: \"peer0.org1.example.com\",\n    })))\nconn, err := grpc.DialContext(ctx, \"peer0.org1.example.com:7051\", dialOpts...)","handlingStrategy":"try-catch","validationCode":"// Pre-check connectivity before calling the gateway\nconn, err := net.DialTimeout(\"tcp\", \"peer0.org1.example.com:7051\", 5*time.Second)\nif err != nil {\n    return fmt.Errorf(\"peer unreachable before gateway call: %w\", err)\n}\nconn.Close()","typeGuard":null,"tryCatchPattern":"conn, err := gw.NewConnection(ctx, address)\nif err != nil {\n    var gwErr *GatewayError\n    if errors.As(err, &gwErr) && strings.Contains(err.Error(), \"failed to create new connection\") {\n        // inspect wrapped grpc error: DNS, TLS, timeout; retry with backoff or fail fast\n        return fmt.Errorf(\"cannot reach peer %s: %w\", address, err)\n    }\n    return err\n}","preventionTips":["Validate connection profile hostnames and ports before deployment.","Always configure TLS credentials (CA cert, server name override) explicitly.","Test node reachability with openssl s_client or grpc_health_probe in CI.","Use a context with a reasonable dial timeout and log the wrapped root error."],"tags":["grpc","network","connection","fabric-gateway"],"backgroundTag":"grpc-dial-connection-failed","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"}