Inspect Swarm Tasks with docker node ps

You will finish with a small set of commands for inspecting the tasks assigned to Docker Swarm nodes, finding failed tasks, and collecting task IDs without scraping a human-oriented table. The examples match the installed Docker Community CLI 29.8.1 from docker-ce-cli package version 5:29.8.1-1~ubuntu.24.04~noble.

Allow about ten minutes. You need the Docker CLI, access to a Docker daemon, and a Swarm manager context. The command is read-only: it does not restart tasks, change node availability, remove nodes or alter services. You normally do not need elevated privileges in the shell, but your Docker context must have permission to query the daemon.

1. Confirm the command and the Swarm context

Start with the local help output. This checks the exact command installed on your machine and requires no manager access:

$ docker node ps --help
Usage:  docker node ps [OPTIONS] [NODE...]

List tasks running on one or more nodes, defaults to current node

The syntax is docker node ps [OPTIONS] [NODE...]. With no node argument, Docker uses the current node. The command works with Swarm, and Docker requires it to be run against a manager node. A regular worker, a non-Swarm daemon, or a context pointing at the wrong host will fail before there is any task output.

Checkpoint: inspect the active context before interpreting an empty or failed result:

$ docker context show
default
$ docker info --format '{{.Swarm.LocalNodeState}} {{.Swarm.ControlAvailable}}'
active true

The exact context name and Swarm fields depend on your setup. If the second command reports that this is not a manager, switch to an approved manager context or ask the Swarm operator for one. Do not initialise a new Swarm just to make this query work. docker swarm init changes cluster state and is outside this guide.

2. List tasks on the current node

Run the command without a node name:

$ docker node ps
ID             NAME        IMAGE          NODE       DESIRED STATE   CURRENT STATE           ERROR   PORTS
abc123def456   web.1       example/web   manager-1  Running         Running 2 minutes ago

Your columns and rows will differ. The table normally includes the task ID, task name, image, node, desired state, current state, error and published ports. The default is the current node, not every node in the Swarm. That default is the most common source of an apparently incomplete result.

To inspect a named node, pass its name or ID:

$ docker node ps NODE_NAME

Replace NODE_NAME with a value from docker node ls. To inspect several nodes, pass them as separate arguments:

$ docker node ps NODE_A NODE_B

Checkpoint: if a task you expected is absent, first confirm the node argument, the active context and the manager requirement. Then check whether the task has already shut down or moved. A missing row is not proof that the service has never run.

3. Find tasks in a particular state

Use the --filter option with a key and value. The installed command supports filters for task name, task ID, label and desired state. For example, show tasks whose desired state is shutdown:

$ docker node ps --filter desired-state=shutdown NODE_NAME

The supported desired-state values are running, shutdown and accepted. A shutdown task can explain a failed deployment or a replacement task that is now running. The filter describes the task record Docker knows about; it is not a request to stop anything.

Name matching accepts all or part of a task name:

$ docker node ps --filter name=web NODE_NAME

For a label-only filter, quote the expression when that makes the boundary clearer:

$ docker node ps --filter 'label=environment' NODE_NAME

You can pass more than one filter. Docker applies the filters together, so verify that the combination is not narrower than intended:

$ docker node ps --filter desired-state=running --filter name=web NODE_NAME

Checkpoint: remove filters and repeat the node query if the result is empty. This distinguishes 'no task matches' from 'the node has no tasks' without changing anything on the cluster.

4. Preserve IDs and avoid misleading truncation

The normal table shortens values to keep it readable. For investigation, retain the complete task ID and stop Docker mapping IDs to names with these read-only options:

$ docker node ps --no-trunc --no-resolve NODE_NAME

--no-trunc prevents output values from being shortened. --no-resolve prevents IDs from being mapped to names where Docker would normally resolve them. Use these switches when copying an ID into a follow-up command or comparing output from two systems. They do not change the task or node.

If another command needs only task IDs, use quiet mode:

$ docker node ps --quiet NODE_NAME
abc123def4567890...

Quiet output is intended for command pipelines, but the displayed ID can still be shortened unless you also use --no-trunc:

$ docker node ps --quiet --no-trunc NODE_NAME

Do not parse the default table by column position. Its spacing is for people, and image names, errors and ports can contain spaces or vary across versions.

5. Create stable, small reports with a Go template

Use --format when a script needs selected fields. The supported placeholders include .ID, .Name, .Image, .Node, .DesiredState, .CurrentState, .Error and .Ports:

$ docker node ps --format '{{.Name}} {{.Node}} {{.DesiredState}} {{.CurrentState}}' NODE_NAME
web.1 manager-1 Running Running 2 minutes ago

Without the table directive, Docker prints exactly the fields declared by the template and does not add headings. That makes the output easier to read in a log, but it is still text rather than a versioned data interchange format. Treat values as untrusted input if you feed them to another program, and quote shell variables rather than building an unquoted command line.

To keep a heading for a human report, use the table directive:

$ docker node ps --format 'table {{.Name}}\t{{.CurrentState}}\t{{.Error}}' NODE_NAME
NAME    CURRENT STATE   ERROR
web.1   Running

Checkpoint: run the formatted command once without redirecting it. Confirm that the selected fields are sufficient before sending the output to a file or monitoring job.

6. Handle failures without making a cluster change

If the command says that the node is not a Swarm manager, check the context and manager status from step 1. If it reports a missing node, compare the argument with docker node ls. If the daemon is unreachable, fix the context or Docker service access rather than retrying a state-changing command.

A task with a non-empty error field is evidence to investigate, not a reason to remove it immediately. Capture the full, untruncated view first:

$ docker node ps --no-trunc --format 'table {{.ID}}\t{{.Name}}\t{{.DesiredState}}\t{{.CurrentState}}\t{{.Error}}' NODE_NAME

This guide has no undo step because every example only queries Docker. Do not add docker service update, docker node update, docker node rm or docker swarm leave to a troubleshooting copy-and-paste block: those commands change scheduling or cluster membership and need a separate change plan.