docker/cli · error

failed to create network

Error message

failed to create network %s: %w

What it means

Raised by createNetworks when NetworkCreate fails for a stack-managed (non-external) network. Stack deploy creates overlay networks named <stack>_<network>; the wrapped %w carries the daemon error (driver unavailable, name collision, label error).

Solutions

1. Confirm the node is a swarm manager and overlay networking is available.
2. Read the wrapped error; a name collision means removing the stray network: `docker network rm <name>`.
3. Check for CIDR overlaps with existing networks and adjust subnet config in compose.
4. Validate driver/options in compose for the network that failed.

Example fix

// before: CIDR overlap with existing network
networks:
  front:
    ipam:
      config:
        - subnet: 172.16.0.0/16  # collides
// after: use a unique subnet
networks:
  front:
    ipam:
      config:
        - subnet: 10.20.0.0/16

// Pre-check: manager status and network name collisions before deploy
info, err := c.Info(ctx, client.InfoOptions{})
if err != nil { return err }
if !info.Info.Swarm.ControlAvailable { return errors.New("not a swarm manager") }
// Check for a stray network with the target name lacking the stack label
for name := range stackNetworks {
    if res, err := c.NetworkInspect(ctx, name, client.NetworkInspectOptions{}); err == nil {
        if _, ok := res.Network.Labels["com.docker.stack.namespace"]; !ok {
            return fmt.Errorf("network %q exists outside any stack; remove or rename", name)
        }
    }
}

if err := stackDeploy(ctx, cli, opts, cfg); err != nil {
    if strings.Contains(err.Error(), "failed to create network") {
        // inspect wrapped error; remove stray network and retry
    }
    return err
}

When it happens

Trigger: Deploying a stack where a network is not marked external (so createNetworks tries NetworkCreate at deploy_composefile.go:195) and the daemon rejects the creation. Triggers when the overlay driver is unavailable, a same-named network already exists outside the stack, or network option conversion produced invalid params.

Common situations: Deploying on a node that is not a swarm manager or has no overlay driver; a leftover network from a previous stack with the same name but no stack label; invalid driver options in compose; overlapping CIDRs across networks.

Related errors

• network is declared as external, but could not be found…
• network is declared as external, but it is not in the right…
• failed to create secret
• failed to create config
• failed to create service

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/6e54ccf5021d9f9c. Report an issue: GitHub.

Appendix: source

Thrown at cli/command/stack/deploy_composefile.go:196

	}

	existingNetworkMap := make(map[string]network.Summary)
	for _, nw := range existingNetworks.Items {
		existingNetworkMap[nw.Name] = nw
	}

	for name, createOpts := range networks {
		if _, exists := existingNetworkMap[name]; exists {
			continue
		}

		if createOpts.Driver == "" {
			createOpts.Driver = defaultNetworkDriver
		}

		_, _ = fmt.Fprintln(dockerCLI.Out(), "Creating network", name)
		if _, err := apiClient.NetworkCreate(ctx, name, createOpts); err != nil {
			return fmt.Errorf("failed to create network %s: %w", name, err)
		}
	}
	return nil
}

func deployServices(ctx context.Context, dockerCLI command.Cli, services map[string]swarm.ServiceSpec, namespace convert.Namespace, sendAuth bool, resolveImage string) ([]string, error) {
	apiClient := dockerCLI.Client()
	out := dockerCLI.Out()

	existingServices, err := getStackServices(ctx, apiClient, namespace.Name())
	if err != nil {
		return nil, err
	}

	existingServiceMap := make(map[string]swarm.Service)
	for _, svc := range existingServices.Items {
		existingServiceMap[svc.Spec.Name] = svc
	}

View on GitHub (pinned to 4f84911bfe)