hyperledger/fabric · critical

failed to create new connection

Error message

failed to create new connection: %w

What it means

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.

Solutions

1. Inspect the wrapped error (%w) to identify the root cause: DNS, connection refused, TLS, or timeout.
2. Verify the peer/orderer address and port in the connection profile or endpoint config are correct and reachable (test with nc/openssl s_client).
3. Check TLS settings: ensure the correct CA certificate, server name override, and client key/cert are configured.
4. If behind NAT/Docker, expose the node's port or use a resolvable hostname instead of the internal service name.
5. Retry with a longer context deadline if the failure is due to slow network/dial timeout.

Example fix

// before
conn, err := grpc.DialContext(ctx, "peer0.org1:7051", dialOpts...)
if err != nil {
    return nil, fmt.Errorf("failed to create new connection: %w", err)
}
// after
// ensure correct address and TLS creds:
certPool := x509.NewCertPool()
certPool.AppendCertsFromPEM(tlsCACert)
dialOpts = append(dialOpts,
    grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{
        RootCAs:            certPool,
        ServerNameOverride: "peer0.org1.example.com",
    })))
conn, err := grpc.DialContext(ctx, "peer0.org1.example.com:7051", dialOpts...)

// Pre-check connectivity before calling the gateway
conn, err := net.DialTimeout("tcp", "peer0.org1.example.com:7051", 5*time.Second)
if err != nil {
    return fmt.Errorf("peer unreachable before gateway call: %w", err)
}
conn.Close()

conn, err := gw.NewConnection(ctx, address)
if err != nil {
    var gwErr *GatewayError
    if errors.As(err, &gwErr) && strings.Contains(err.Error(), "failed to create new connection") {
        // inspect wrapped grpc error: DNS, TLS, timeout; retry with backoff or fail fast
        return fmt.Errorf("cannot reach peer %s: %w", address, err)
    }
    return err
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• failed to create new connection
• connection to ( ) is in state
• connection to ( ) is in state
• connection to terminated
• could not connect to ordering service

AI-assisted analysis of hyperledger/fabric@2736b63f8f (2026-09-04). Data as JSON: /api/errors/765af5bc2f1a75ce. Report an issue: GitHub.

Appendix: source

Thrown at internal/pkg/gateway/endpoint.go:135

		},
		DialTimeout:  ef.timeout,
		AsyncConnect: true,
	}
	dialOpts, err := config.DialOptions()
	if err != nil {
		return nil, err
	}

	ctx, cancel := context.WithTimeout(context.Background(), ef.timeout)
	defer cancel()

	dialer := ef.dialer
	if dialer == nil {
		dialer = grpc.DialContext
	}
	conn, err := dialer(ctx, address, dialOpts...)
	if err != nil {
		return nil, fmt.Errorf("failed to create new connection: %w", err)
	}
	return conn, nil
}

View on GitHub (pinned to 2736b63f8f)