@@ -181,6 +181,16 @@ func (n *networkRouter) postNetworkCreate(ctx context.Context, w http.ResponseWr

 	nw, err := n.backend.CreateNetwork(create)

 	if err != nil {

+		var warning string

+		if _, ok := err.(libnetwork.NetworkNameError); ok {

+			// check if user defined CheckDuplicate, if set true, return err

+			// otherwise prepare a warning message

+			if create.CheckDuplicate {

+				return libnetwork.NetworkNameError(create.Name)

+			}

+			warning = libnetwork.NetworkNameError(create.Name).Error()

+		}

+

 		if _, ok := err.(libnetwork.ManagerRedirectError); !ok {

 			return err

 		}

@@ -188,7 +198,10 @@ func (n *networkRouter) postNetworkCreate(ctx context.Context, w http.ResponseWr

 		if err != nil {

 			return err

 		}

-		nw = &types.NetworkCreateResponse{ID: id}

+		nw = &types.NetworkCreateResponse{

+			ID:      id,

+			Warning: warning,

+		}

 	}

 	return httputils.WriteJSON(w, http.StatusCreated, nw)

@@ -6288,7 +6288,7 @@ paths:

                 description: "The network's name."

                 type: "string"

               CheckDuplicate:

-                description: "Check for networks with duplicate names."

+                description: "Check for networks with duplicate names. Since Network is primarily keyed based on a random ID and not on the name, and network name is strictly a user-friendly alias to the network which is uniquely identified using ID, there is no guaranteed way to check for duplicates. CheckDuplicate is there to provide a best effort checking of any networks which has the same name but it is not guaranteed to catch all name collisions."

                 type: "boolean"

               Driver:

                 description: "Name of the network driver plugin to use."

@@ -416,6 +416,13 @@ type EndpointResource struct {

 // NetworkCreate is the expected body of the "create network" http request message

 type NetworkCreate struct {

+	// Check for networks with duplicate names.

+	// Network is primarily keyed based on a random ID and not on the name.

+	// Network name is strictly a user-friendly alias to the network

+	// which is uniquely identified using ID.

+	// And there is no guaranteed way to check for duplicates.

+	// Option CheckDuplicate is there to provide a best effort checking of any networks

+	// which has the same name but it is not guaranteed to catch all name collisions.

 	CheckDuplicate bool

 	Driver         string

 	EnableIPv6     bool

@@ -248,6 +248,8 @@ func (daemon *Daemon) createNetwork(create types.NetworkCreateRequest, id string

 		}

 	}

 	if nw != nil {

+		// check if user defined CheckDuplicate, if set true, return err

+		// otherwise prepare a warning message

 		if create.CheckDuplicate {

 			return nil, libnetwork.NetworkNameError(create.Name)

 		}

@@ -2838,7 +2838,12 @@ Content-Type: application/json

 **JSON parameters**:

 - **Name** - The new network's name. this is a mandatory field

-- **CheckDuplicate** - Requests daemon to check for networks with same name. Defaults to `false`

+- **CheckDuplicate** - Requests daemon to check for networks with same name. Defaults to `false`.

+    Since Network is primarily keyed based on a random ID and not on the name, 

+    and network name is strictly a user-friendly alias to the network which is uniquely identified using ID, 

+    there is no guaranteed way to check for duplicates across a cluster of docker hosts. 

+    This parameter CheckDuplicate is there to provide a best effort checking of any networks 

+    which has the same name but it is not guaranteed to catch all name collisions.

 - **Driver** - Name of the network driver plugin to use. Defaults to `bridge` driver

 - **IPAM** - Optional custom IP scheme for the network

   - **Driver** - Name of the IPAM driver to use. Defaults to `default` driver

@@ -3167,7 +3167,12 @@ Content-Type: application/json

 **JSON parameters**:

 - **Name** - The new network's name. this is a mandatory field

-- **CheckDuplicate** - Requests daemon to check for networks with same name. Defaults to `false`

+- **CheckDuplicate** - Requests daemon to check for networks with same name. Defaults to `false`.

+    Since Network is primarily keyed based on a random ID and not on the name, 

+    and network name is strictly a user-friendly alias to the network 

+    which is uniquely identified using ID, there is no guaranteed way to check for duplicates. 

+    This parameter CheckDuplicate is there to provide a best effort checking of any networks 

+    which has the same name but it is not guaranteed to catch all name collisions.

 - **Driver** - Name of the network driver plugin to use. Defaults to `bridge` driver

 - **IPAM** - Optional custom IP scheme for the network

   - **Driver** - Name of the IPAM driver to use. Defaults to `default` driver

@@ -3281,7 +3281,12 @@ Content-Type: application/json

 **JSON parameters**:

 - **Name** - The new network's name. this is a mandatory field

-- **CheckDuplicate** - Requests daemon to check for networks with same name. Defaults to `false`

+- **CheckDuplicate** - Requests daemon to check for networks with same name. Defaults to `false`.

+    Since Network is primarily keyed based on a random ID and not on the name, 

+    and network name is strictly a user-friendly alias to the network 

+    which is uniquely identified using ID, there is no guaranteed way to check for duplicates. 

+    This parameter CheckDuplicate is there to provide a best effort checking of any networks 

+    which has the same name but it is not guaranteed to catch all name collisions.

 - **Driver** - Name of the network driver plugin to use. Defaults to `bridge` driver

 - **Internal** - Restrict external access to the network

 - **IPAM** - Optional custom IP scheme for the network

@@ -3346,7 +3346,12 @@ Content-Type: application/json

 **JSON parameters**:

 - **Name** - The new network's name. this is a mandatory field

-- **CheckDuplicate** - Requests daemon to check for networks with same name. Defaults to `false`

+- **CheckDuplicate** - Requests daemon to check for networks with same name. Defaults to `false`.

+    Since Network is primarily keyed based on a random ID and not on the name, 

+    and network name is strictly a user-friendly alias to the network 

+    which is uniquely identified using ID, there is no guaranteed way to check for duplicates. 

+    This parameter CheckDuplicate is there to provide a best effort checking of any networks 

+    which has the same name but it is not guaranteed to catch all name collisions.

 - **Driver** - Name of the network driver plugin to use. Defaults to `bridge` driver

 - **Internal** - Restrict external access to the network

 - **IPAM** - Optional custom IP scheme for the network