Inspect Docker Swarm Nodes Safely with docker node inspect

docker node inspect reads everything Swarm knows about a node, from role and availability to reachability, without changing a single thing. This guide covers reading one node or several, picking out fields with a Go template, and recognising the manager-only failure that has nothing to do with the node you are inspecting. Allow about ten minutes. You need Docker CLI access and a Swarm manager context. The examples use Docker CE CLI 29.8.1, installed here as package version 5:29.8.1-1~ubuntu.24.04~noble.

It does not promote, demote, remove or update a node. Those state-changing jobs belong to other docker node subcommands and are outside this guide.

1. Confirm the command and Docker version

Start with local help. This is an ordinary command and does not need elevated privileges:

$ docker node inspect --help
Usage:  docker node inspect [OPTIONS] self|NODE [NODE...]

Display detailed information on one or more nodes

Options:
  -f, --format string   Format output using a custom template:
                        'json': Print in JSON format
                        'TEMPLATE': Use the supplied Go template
      --pretty          Print information in a human friendly format

Check the client version as well:

$ docker --version
Docker version 29.8.1, build 4a63305
$ dpkg-query -W -f='${Package} ${Version}\n' docker-ce-cli
docker-ce-cli 5:29.8.1-1~ubuntu.24.04~noble

The build identifier and package revision can differ on another host. Use the output from your own machine when investigating version-specific behaviour.

2. Check the active context without changing it

Node inspection talks to the Docker Engine selected by the current context. Display the context name and endpoint:

$ docker context show
default
$ docker context ls
NAME        DESCRIPTION                               DOCKER ENDPOINT               ERROR
default *   Current DOCKER_HOST based configuration   unix:///var/run/docker.sock

Your table will differ. A remote context may point to a manager, while default may point to a standalone Engine. Context inspection is read-only, but treat a context containing a remote or production endpoint as security-sensitive: node details can include hostnames, addresses and platform data.

Only a Swarm manager can run this cluster management command. A worker, a standalone Engine, or a context that cannot reach its daemon will not produce node details.

3. Inspect the current manager node

On a manager, self names the node associated with that manager. Use it when you want to verify the current manager before looking up another node:

$ docker node inspect self
[
  {
    "ID": "NODE_ID",
    "Spec": {
      "Role": "manager",
      "Availability": "active"
    },
    "Status": {
      "State": "ready",
      "Addr": "MANAGER_ADDRESS"
    }
  }
]

The real response contains more fields. The output is a JSON array even when only one node is selected. Hostnames, IDs, timestamps, addresses and engine versions are deployment-specific, so do not copy a sample value into an automation script.

A successful command does not mean every node is healthy. Read Status.State, Status.Addr, Spec.Role and Spec.Availability together: a node can be present in the manager's view but unavailable for scheduling.

4. Inspect a named node or several nodes

Replace NODE_NAME_OR_ID with the exact name or ID returned by your cluster's node listing:

$ docker node ls
ID                            HOSTNAME       STATUS    AVAILABILITY   MANAGER STATUS
NODE_ID                       swarm-manager  Ready     Active         Leader

$ docker node inspect NODE_NAME_OR_ID

Names and IDs are positional arguments, and you can pass more than one:

$ docker node inspect NODE_A NODE_B

Keep each node as a separate shell argument. Quote a name only when it contains shell-significant characters. If a name is wrong, Docker reports that the node cannot be found; check docker node ls rather than guessing an ID.

5. Select one field with --format

Use a Go template when a full JSON response is too noisy. This prints the manager flag for each selected node:

$ docker node inspect --format '{{ .ManagerStatus.Leader }}' NODE_NAME_OR_ID
true

Template expressions use the fields in the inspect response. This example prints the node's state, availability and address on one line:

$ docker node inspect --format 'state={{ .Status.State }} availability={{ .Spec.Availability }} address={{ .Status.Addr }}' NODE_NAME_OR_ID
state=ready availability=active address=MANAGER_ADDRESS

The output is one rendered result per node. Field names are case-sensitive, and a missing or unsuitable field may render as an empty value, so test a template against one known node before putting it into a monitoring script.

For machine-readable output, request JSON through the same option:

$ docker node inspect --format json NODE_NAME_OR_ID
{"ID":"NODE_ID","Spec":{"Role":"manager","Availability":"active"},"Status":{"State":"ready","Addr":"MANAGER_ADDRESS"}}

The exact JSON is version- and node-dependent. If another tool will parse it, pass the command's output directly to that tool rather than matching a formatted human-readable line.

6. Use --pretty for a quick human check

--pretty gives a compact report intended for a person reading at a terminal:

$ docker node inspect --pretty NODE_NAME_OR_ID
ID:                     NODE_ID
Hostname:               swarm-manager
Status:
 State:                 Ready
 Availability:          Active
 Address:               MANAGER_ADDRESS

On the installed CLI, --format=pretty is also accepted by the Docker documentation as the equivalent format selection. Prefer --pretty in a short interactive command because its purpose is immediately visible. Do not parse aligned spaces from this display in a script; use an explicit template or JSON instead.

7. Diagnose the manager-only failure

Run the smallest safe test against the active context:

$ docker node inspect self
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.
$ printf 'exit status: %s\n' "$?"
exit status: 1

This is an expected result on a standalone Engine or Swarm worker. Warning: it is not a prompt to run docker swarm init. Initialising a Swarm changes the daemon's cluster state and may affect how the host is administered. Joining a Swarm also changes state and requires the correct manager-issued token and advertised address. Stop here unless cluster membership is an explicitly approved operational task.

If you expected a manager, recheck the context, daemon endpoint and access rights with read-only commands. Ask a cluster administrator for the correct manager context. Elevated privileges can solve a local socket permission problem, but they cannot turn a worker into a manager.

There is no undo step for any inspection example, because the command does not modify Docker state. If you later change Swarm membership as a separate approved task, use that task's documented recovery plan rather than treating inspection as its rollback.