🐳 Docker Error Guide: 'This node is not a swarm manager' service Commands

Exact Error Message

$ docker service ls
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.

The identical message appears from any orchestration subcommand — docker stack deploy, docker node ls, or docker service create:

$ docker stack deploy -c docker-compose.yml web
This node is not a swarm manager. Worker nodes can't be used to view or modify cluster state. Please run this command on a manager node or promote the current node to a manager.

What It Means

docker service, docker stack, docker node, and docker secret are Swarm-mode commands. They operate on cluster state (the Raft store) that only manager nodes hold. If the daemon you are talking to is not part of a swarm at all, or is a worker rather than a manager, it has no access to that state and rejects the command with This node is not a swarm manager.

This is an orchestration-mode mismatch, not a container or image error. The engine is running fine for plain docker run; it simply is not acting as a swarm manager, so cluster-scoped commands have nothing to talk to.

Common Causes

• Swarm mode was never initialized on this host (docker swarm init was never run).
• You are on a worker node, which cannot read or modify cluster state.
• The node left the swarm (docker swarm leave) or was demoted from manager to worker.
• Commands are being sent — via docker context or DOCKER_HOST — to a standalone engine instead of the manager.
• A single-node setup was reset (Docker reinstalled, daemon data pruned) and swarm state was lost.
• Confusing docker stack deploy (Swarm) with docker compose up (standalone Compose), which does not need a swarm.

Diagnostic Commands

Check whether Swarm mode is active and what role this node holds:

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

LocalNodeState: active with Manager: true means this node is a manager. inactive means no swarm at all.

If a swarm exists, list nodes to see roles (this itself only works on a manager):

docker node ls

Confirm which endpoint you are actually talking to:

docker context ls
echo "DOCKER_HOST=$DOCKER_HOST"

Reproduce the failure to capture the exact wording:

docker service ls

Step-by-Step Resolution

1. Determine the current state. If docker info shows Swarm: inactive, no swarm exists and you need to create one. If it shows active but Manager: false, you are on a worker and must run the command elsewhere.

2. For a fresh single-node or lab setup, initialize the swarm on this host, which makes it the first manager:

docker swarm init

If the host has multiple interfaces, pin the advertise address:

docker swarm init --advertise-addr 10.0.0.5

3. Confirm the node is now a reachable manager:

docker node ls

You should see this node with MANAGER STATUS: Leader.

4. If a swarm already exists and this is a worker, either run the command on a manager, or promote this node from a manager:

# run on an existing manager
docker node promote <this-node-name>

5. If your CLI is pointed at the wrong engine, switch to the manager’s context or unset a misdirected DOCKER_HOST:

docker context use manager-prod
# or
unset DOCKER_HOST

6. Re-run the original orchestration command and confirm it now works:

docker stack deploy -c docker-compose.yml web
docker service ls

Prevention

• Standardise the target of orchestration commands with a dedicated docker context for the swarm manager so no one runs docker service against a standalone engine.
• Keep at least three managers in production swarms; a single manager means losing it takes the whole control plane offline.
• Document clearly whether an environment uses Swarm (docker stack/service) or plain Compose (docker compose) — mixing the two mental models is the most common source of this error.
• Guard automation with a docker info role check before issuing swarm commands, so scripts fail with a clear message instead of a raw daemon error.
• Back up the swarm state (/var/lib/docker/swarm) on managers so a reinstall does not silently drop the cluster.

Related Errors

• docker swarm init → Error response from daemon: This node is already part of a swarm — the inverse; swarm already exists.
• rpc error: code = Unavailable ... the swarm does not have a leader — a quorum problem on an existing swarm, not a missing manager role.
• Error response from daemon: This node is not part of a swarm — you left the swarm entirely; rejoin or re-init.
• no such service — a valid manager, but the named service does not exist; a different lookup failure.

Frequently Asked Questions

What is the difference between docker stack and docker compose? docker stack deploy schedules services onto a Swarm cluster and requires a manager node. docker compose up runs containers on a single standalone engine and needs no swarm. This error only comes from the Swarm-mode commands.

Do I need multiple machines to use Swarm? No. docker swarm init on a single host creates a one-node swarm that acts as its own manager — enough for learning and small deployments. Production should use multiple managers for high availability.

Why can’t worker nodes run docker service ls? Workers do not hold the Raft cluster state; only managers do. Run cluster commands on a manager, or promote the worker with docker node promote. You can script that role check with a prompt from the DevOps AI prompt library at /prompts/?stack=docker.

I ran docker swarm init before — why is it inactive now? The node likely left the swarm, was demoted, or lost its /var/lib/docker/swarm state through a reinstall or prune. Check docker info; if Swarm: inactive, re-initialize or rejoin.

How do I point my CLI at the manager instead of a local engine? Create a docker context for the manager’s endpoint and select it with docker context use, or unset a stray DOCKER_HOST. For more orchestration fixes, see the Docker guides.