What causes "failed to create new connection: %w" in hyperledger/fabric?

Inspect the wrapped error (%w) to identify the root cause: DNS, connection refused, TLS, or timeout.

failed to create new connection: %w

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.

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)

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.

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...)

Defensive patterns

Strategy: try-catch

Validate before calling

// 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()

Try / catch

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
}

Prevention

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.

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

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