🐳 Docker Error Guide: 'This node is not a swarm manager' creating an overlay network

Exact Error Message

$ docker network create --driver overlay my_overlay
Error response from daemon: This node is not a swarm manager. Use "docker swarm init" or "docker swarm join" to connect this node to swarm and try again.

Depending on the daemon version and how the network is requested, you may instead see:

Error response from daemon: cannot create overlay network. Overlay networks require swarm mode. Please run `docker swarm init` and try again.

What It Means

The overlay driver builds a multi-host virtual network so containers on different Docker daemons can talk to each other over an encrypted VXLAN tunnel. That coordination is handled by the swarm control plane: the manager nodes store network state in the Raft log and distribute it to workers. Without swarm mode active, there is no control plane to own the network, so the daemon refuses to create it.

This node is not a swarm manager means the daemon is running in standalone mode (never initialized a swarm) or the node is a worker that cannot perform management operations. Overlay creation, like secrets and services, is a manager-only operation.

Common Causes

• The daemon was never put into swarm mode; you are running a plain single-host Docker.
• You ran the command on a worker node instead of a manager.
• The node left the swarm (docker swarm leave) and reverted to standalone mode.
• You copied a multi-host Compose or script onto a laptop that is not part of any swarm.
• You actually want a single-host user-defined network and reached for overlay when bridge was appropriate.
• The swarm was demoted or the manager quorum was lost, dropping the node out of manager status.

Diagnostic Commands

Check whether swarm mode is active and whether this node is a manager:

docker info --format 'Swarm: {{.Swarm.LocalNodeState}}  Manager: {{.Swarm.ControlAvailable}}'

If swarm is active, list nodes to see manager vs worker roles (managers only):

docker node ls

List existing networks and their drivers/scopes to see what is already defined:

docker network ls

Inspect the address pool if you plan to create an overlay, to avoid subnet clashes:

docker network inspect ingress --format '{{json .IPAM.Config}}'

Step-by-Step Resolution

1. Decide what you actually need. If everything runs on one host, you do not need an overlay at all; a user-defined bridge gives you DNS-based service discovery locally:

docker network create --driver bridge my_bridge

2. If you genuinely need multi-host networking, initialize swarm mode on the node that should be the manager:

docker swarm init --advertise-addr 10.0.0.10

3. Now create the overlay network from the manager. Add --attachable if standalone containers (not just swarm services) must join it:

docker network create --driver overlay --attachable my_overlay

4. Join additional hosts as workers using the token printed by swarm init:

docker swarm join --token SWMTKN-1-xxxx 10.0.0.10:2377

5. Attach a service or a standalone container to the overlay to confirm it works:

docker service create --name web --network my_overlay nginx
docker run -d --network my_overlay --name test busybox sleep 3600

6. If the node used to be a manager but lost that role, promote it (from an existing manager) or re-init if the swarm is gone:

docker node promote <node-id>

Prevention

• Standardize on docker swarm init in your provisioning so overlay-dependent stacks always land on a manager. The DevOps AI prompt library can generate a bootstrap snippet that checks Swarm.ControlAvailable before creating overlays.
• Guard scripts with a precheck: bail out early if docker info shows the node is not a manager, instead of failing halfway through a stack deploy.
• Use bridge networks for single-host development and reserve overlay for genuine multi-host clusters, so you never reach for the wrong driver.
• Mark overlays --attachable only when standalone containers must join; otherwise keep them swarm-service-only to reduce surface area.
• Keep an odd number of managers (3 or 5) so you do not lose quorum and silently demote nodes out of manager status.

Related Errors

• Error response from daemon: could not find an available, non-overlapping IPv4 address pool — swarm is active but address pools collide.
• network <name> not found — the overlay was created on a different node or already removed.
• swarm has no active managers — quorum is lost, so no manager operations succeed.
• only a single manager can leave a swarm without --force — a different swarm lifecycle guard.

Frequently Asked Questions

Do I need swarm mode just to use container DNS? No. A user-defined bridge network gives you automatic DNS-based discovery between containers on a single host. Overlay is only for spanning multiple hosts.

Can I create an overlay network on a worker node? No. Network creation is a manager-only operation. Run it against a manager and the swarm distributes the network to workers automatically when services schedule there.

What does --attachable do? It lets standalone containers started with docker run --network my_overlay join the overlay, not just swarm-managed service tasks. Without it, only services can attach.

I ran docker swarm init but still get the error, why? You are probably on a different node or a worker. Confirm with docker info that this specific daemon shows ControlAvailable: true.

Is a single-node swarm valid just to use overlay networks? Yes, docker swarm init on one host creates a one-node swarm and overlay networks work, though for a single host a bridge network is simpler. For more, see the Docker guides.