diff --git a/api/server/router/network/network_routes.go b/api/server/router/network/network_routes.go
index 970a391f3d..47d50b5cc4 100644
--- a/api/server/router/network/network_routes.go
+++ b/api/server/router/network/network_routes.go
@@ -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)
diff --git a/api/swagger.yaml b/api/swagger.yaml
index 3188e18443..3a44ac0bab 100644
--- a/api/swagger.yaml
+++ b/api/swagger.yaml
@@ -6218,7 +6218,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."
diff --git a/api/types/types.go b/api/types/types.go
index 520eb77b9d..509a78b633 100644
--- a/api/types/types.go
+++ b/api/types/types.go
@@ -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
diff --git a/daemon/network.go b/daemon/network.go
index 8e42824ba8..1a1a429535 100644
--- a/daemon/network.go
+++ b/daemon/network.go
@@ -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)
 		}
diff --git a/docs/api/v1.21.md b/docs/api/v1.21.md
index cadfdbd2a4..7b40b7b8c9 100644
--- a/docs/api/v1.21.md
+++ b/docs/api/v1.21.md
@@ -2836,7 +2836,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
diff --git a/docs/api/v1.22.md b/docs/api/v1.22.md
index 8dcd8c552e..3fe36c8d97 100644
--- a/docs/api/v1.22.md
+++ b/docs/api/v1.22.md
@@ -3165,7 +3165,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
diff --git a/docs/api/v1.23.md b/docs/api/v1.23.md
index 8ac2e2538e..68e17e4abd 100644
--- a/docs/api/v1.23.md
+++ b/docs/api/v1.23.md
@@ -3279,7 +3279,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
diff --git a/docs/api/v1.24.md b/docs/api/v1.24.md
index 30b2a9f588..5a9cf16ea5 100644
--- a/docs/api/v1.24.md
+++ b/docs/api/v1.24.md
@@ -3344,7 +3344,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