Inspect Docker Swarm Tasks Without Losing the Useful Detail

You will finish with a repeatable way to inspect the tasks belonging to a Docker Swarm stack, narrow the result to a node or state, and switch between human-readable and script-friendly output. The examples use Docker CE CLI 29.8.1, 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 stack name. The command is a cluster-management operation: it must run against a Swarm manager. It normally does not need sudo. A worker node, a stopped daemon or a non-Swarm Docker context cannot provide the task list.

1. Check the installed command

Start with read-only checks. This confirms the binary, version and option spelling before you build a diagnostic command:

$ command -v docker
/usr/bin/docker
$ docker --version
Docker version 29.8.1, build 4a63305
$ docker stack ps --help
Usage:  docker stack ps [OPTIONS] STACK

The final argument is mandatory. It is the stack name, not a service name and not a Compose file path. Checkpoint: if the help text is different, use the syntax printed by your installed CLI.

2. List every task in the stack

Replace STACK_NAME with the exact name shown by docker stack ls. Listing stacks is also read-only:

$ docker stack ls
NAME       SERVICES
STACK_NAME 3
$ docker stack ps STACK_NAME

The default table includes the task ID, task name, image, node, desired state, current state, error and ports. The task list may include tasks that have stopped or failed, so do not equate a row's presence with a healthy service. Docker may show abbreviated IDs and image details in the default view.

If Docker says that the node is not a Swarm manager, stop there. Run the command through a Docker context connected to a manager, or ask the person operating the cluster for the appropriate context. Do not run docker swarm init on a production host as a troubleshooting shortcut: that changes cluster state and is outside this inspection workflow.

3. Filter the result to a useful question

Use one --filter flag for a narrow query. The supported filters documented for this command are id, name, node and desired-state:

$ docker stack ps --filter "desired-state=running" STACK_NAME
$ docker stack ps --filter "node=NODE_NAME" STACK_NAME
$ docker stack ps --filter "name=SERVICE_NAME" STACK_NAME
$ docker stack ps --filter "id=TASK_ID_PREFIX" STACK_NAME

Use desired-state=running to focus on tasks the scheduler wants running. It does not guarantee that the current state is running; read the current-state column as well. The documented desired states are running, shutdown, ready and accepted.

Multiple filter flags are combined as an OR filter in the current Docker documentation. For example, this asks for tasks matching either of two names:

$ docker stack ps -f "name=SERVICE_NAME.1" -f "name=SERVICE_NAME.2" STACK_NAME

Checkpoint: quote each complete key=value expression. That keeps shell metacharacters and whitespace from changing what Docker receives.

4. Make output suitable for a script

Use --quiet when a later command only needs task IDs:

$ docker stack ps --quiet STACK_NAME
TASK_ID_1
TASK_ID_2

Do not pass that output blindly into a destructive command. A task ID is an identifier, not a confirmation that the task is safe to remove or alter. If you need details, inspect a selected ID deliberately with a separate command after reviewing the list.

For structured processing, use the built-in JSON format:

$ docker stack ps --format json STACK_NAME
{"CurrentState":"Running ...","DesiredState":"Running","Error":"","ID":"...","Image":"...","Name":"...","Node":"...","Ports":"..."}

Each task is emitted as a JSON object. The values and timestamps are cluster-specific, so parse the fields rather than matching the example text. The command also accepts a Go template. This prints a compact name and image view without table headings:

$ docker stack ps --format '{{.Name}}: {{.Image}}' STACK_NAME
SERVICE_NAME.1: IMAGE_REFERENCE

5. Preserve identifiers and image digests

Use --no-resolve when you need the underlying IDs instead of Docker's name mapping:

$ docker stack ps --no-resolve STACK_NAME

This is useful when names are confusing across nodes or when you are comparing output with lower-level Docker information. Use --no-trunc when the shortened task ID, error text or image reference is not enough:

$ docker stack ps --no-trunc STACK_NAME

Long output can be difficult to scan. A practical diagnostic sequence is to start with the default table, filter the suspected task, then rerun with --no-trunc or --format json only when the extra detail is needed.

6. Diagnose failures without changing the cluster

A missing stack name is a local command error:

$ docker stack ps
docker: 'docker stack ps' requires 1 argument

A plausible name is not enough if the daemon is not connected to a manager. On a non-manager node, the installed CLI reports an error such as:

$ docker stack ps STACK_NAME
Error response from daemon: This node is not a swarm manager.

Check the active context and daemon connection before trying elevated privileges:

$ docker context show
$ docker info
$ docker node ls

docker node ls itself requires manager access, so a failure there is useful evidence rather than a reason to initialise a new Swarm. If the stack exists but no rows match, remove filters and check the exact stack name. If a task shows an error, preserve the full output with --no-trunc before changing a service or redeploying it.

7. Finish with an explicit check

For a routine health review, capture a filtered list and then verify that the result is not empty:

$ docker stack ps --filter "desired-state=running" --format '{{.Name}} {{.CurrentState}} {{.Error}}' STACK_NAME
$ docker stack ps --filter "desired-state=running" -q STACK_NAME | wc -l

The count is only a count of matching tasks. Compare it with the service's intended replica count and inspect current state and error fields before declaring the stack healthy. No command in this guide changes a service, task, stack or Swarm, so there is nothing to undo.