Inspect Docker Swarm Tasks with docker service ps

A replica is missing and docker service ps is how you find out where it went, without touching the service that owns it. You will list a service's tasks, separate current tasks from recent failures, and pull out IDs or specific fields for further digging. The workflow is entirely read-only: this command does not update, restart or remove a service.

Allow about ten minutes. You need Docker CLI from docker-ce-cli and access to a Swarm manager. These examples were checked against Docker CLI 29.8.1, package version 5:29.8.1-1~ubuntu.24.04~noble. You need an active Swarm and a service name that exists in that cluster. It is normally an ordinary user command, though your Docker socket or context may still require its usual access permission.

1. Confirm the local command

Start with read-only checks so you know which client and syntax you are using:

$ docker version --format '{{.Client.Version}}'
29.8.1
$ docker service ps --help
Usage:  docker service ps [OPTIONS] SERVICE [SERVICE...]

List the tasks of one or more services

The installed manpage gives the same shape: one or more service names after the options. Do not confuse this with docker ps, which lists containers on the current Docker host. Swarm tasks are scheduled across the cluster, so their node and desired state matter.

Checkpoint: if the client version is printed and help shows SERVICE [SERVICE...], carry on. If docker is missing or the version is not what you expected, fix the client or context before diagnosing a service.

2. List a service's tasks

Replace SERVICE_NAME with the exact service name. This only reads cluster state:

$ docker service ps SERVICE_NAME
ID             NAME             IMAGE          NODE       DESIRED STATE   CURRENT STATE            ERROR     PORTS
TASK_ID        SERVICE_NAME.1   IMAGE_NAME     NODE_NAME  Running         Running 2 minutes ago

The real column widths and values vary. A normal result includes task ID, task name, image, node, desired state, current state, error and published ports. A replicated service can show more than one current task, and after an update or a failed placement, Docker can also list older shutdown or rejected task attempts underneath. That history is evidence of what happened, not necessarily a task that should still be running.

Do not treat a blank or failed result as proof the service is healthy. Check the exact error column and the command's exit status:

$ docker service ps SERVICE_NAME
$ status=$?
$ printf 'docker service ps exit status: %s\n' "$status"
docker service ps exit status: 0

A non-zero status commonly means the client could not reach the manager, the current context is wrong, the service does not exist, or the command ran against a node that cannot answer this Swarm management request. Confirm the active context and manager access before you touch the service.

3. Show failed or historical tasks

Read the DESIRED STATE, CURRENT STATE and ERROR columns together. A row with desired state Shutdown and a current state such as Rejected is a historical attempt, and its error can explain why a replacement task was scheduled.

For a less distracting view, filter by desired state. The supported values are running, shutdown and accepted:

$ docker service ps --filter 'desired-state=running' SERVICE_NAME
$ docker service ps --filter 'desired-state=shutdown' SERVICE_NAME

These filters do not repair a task; they narrow what you inspect. Multiple --filter flags are combined as an OR, so this requests tasks named either of two slots:

$ docker service ps \
    --filter 'name=SERVICE_NAME.1' \
    --filter 'name=SERVICE_NAME.2' \
    SERVICE_NAME

Supported filter keys are id, name, node and desired-state. Keep the service name as the final argument even when a filter is present.

4. Inspect one node or keep full identifiers

To see tasks placed on one node, filter by its name or ID:

$ docker service ps --filter 'node=NODE_NAME' SERVICE_NAME

Docker resolves IDs to names in the default table, convenient for a person but less useful when matching logs, alerts or API data. Use --no-resolve to keep node IDs visible, or --no-trunc to keep full task IDs, image digests and error messages:

$ docker service ps --no-resolve --no-trunc SERVICE_NAME

Safety boundary: these flags change presentation only. They do not change scheduling, task history or the service definition. Avoid copying a shortened ID into an incident record when the full value is sitting right there.

5. Produce stable, script-friendly output

Use --format when you need a small report rather than the human-oriented table. The installed command accepts a Go template, for example task name, node and current state:

$ docker service ps \
    --format '{{.Name}}\t{{.Node}}\t{{.CurrentState}}\t{{.Error}}' \
    SERVICE_NAME
SERVICE_NAME.1    NODE_NAME    Running 4 minutes ago

Available placeholders include .ID, .Name, .Image, .Node, .DesiredState, .CurrentState, .Error and .Ports. The example above deliberately leaves out a table header, so do not mistake the first output row for a heading in a script: add your own header only when the consumer needs one.

For IDs only, use the dedicated quiet option:

$ docker service ps --quiet SERVICE_NAME
TASK_ID

Combine --quiet with filters when you want IDs for one node or desired state. Treat the result as data, not as a command to execute: task IDs should not be interpolated into a shell command without deliberate quoting and validation.

6. Handle common distractions and errors

This is a Swarm cluster-management command and must run against a manager. A worker-only context, an inactive Swarm, or a service name from another context produces an error or no useful task list. Check the context you selected and ask a cluster administrator for manager access if that is the intended target. Elevated privileges do not turn a worker into a manager, and sudo can select a different Docker configuration or socket, so use it only when your Docker setup explicitly requires it.

Warning: do not respond to a rejected task by immediately removing and recreating the service. First preserve the full output with --no-trunc, record the error, and inspect the image, node and desired state. Update, rollback, scale and removal are separate commands that can disrupt running workloads, and this guide makes none of those changes, so there is nothing here to undo.

Done means