How to fix Error response from daemon: no suitable node (scheduling constraints not satisfied on nodes) in Docker

First, check what constraints are defined for your service:

docker service inspect <service-name> --pretty

Look for the "Placement" section. You can also get just the constraints:

docker service inspect <service-name> --format '{{json .Spec.TaskTemplate.Placement.Constraints}}'

Note down the exact constraint expressions (e.g., node.labels.region==east).

View the tasks to see the full scheduling error:

docker service ps <service-name> --no-trunc

This shows all task attempts and their errors. For more detail on a specific task:

docker inspect <task-id>

The error message often indicates how many nodes were evaluated and why they failed.

Check what nodes exist and their current labels:

docker node ls

To see labels on all nodes:

docker node ls --format '{{.Hostname}}: {{.Status}} {{.Availability}}'

For detailed labels on a specific node:

docker node inspect <node-name> --format '{{json .Spec.Labels}}'

Compare the existing labels against what your constraint requires.

If the label doesn't exist, add it to one or more nodes. Run this from a manager node:

docker node update --label-add <key>=<value> <node-name>

For example, if your constraint is node.labels.region==east:

docker node update --label-add region=east worker-node-1

The service should automatically reconcile and deploy tasks to the now-eligible node.

Ensure the node with matching labels is not in drain mode:

docker node ls

If the node shows "Drain" availability, update it to active:

docker node update --availability active <node-name>

Nodes in drain mode will not accept new tasks, even if they match constraints.

Common typos include:
- mode.role instead of node.role
- node.label instead of node.labels (plural)
- Wrong comparison operator

Valid constraint attributes include:
- node.id - Node ID
- node.hostname - Node hostname
- node.role - manager or worker
- node.platform.os - Operating system
- node.platform.arch - CPU architecture
- node.labels.<key> - Custom node labels

If you need to fix the constraint, update the service:

docker service update --constraint-rm "wrong.constraint==value" \
  --constraint-add "node.labels.correct==value" <service-name>

After fixing the constraint or adding labels, verify the service:

docker service ls
docker service ps <service-name>

Tasks should now show "Running" status. If still pending, check for other issues like resource constraints or port conflicts.