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

DockerINTERMEDIATEMEDIUMUpdated Dec 6, 2025· 158 views

This error occurs when Docker Swarm cannot find any node in the cluster that matches the placement constraints specified for a service. The fix involves adding the required labels to nodes or adjusting your service constraints.

Quick fix

Fixes Error response from daemon: no suitable node (scheduling constraints not satisfied on nodes)

docker service inspect <service-name> --pretty
  1. Inspect the service to see the exact constraint
  2. Check the current task status for detailed error
  3. List nodes and their labels
  4. Add the required label to a node
docker — error
docker service inspect <service-name> --pretty
Error response from daemon: no suitable node (scheduling constraints not satisfied on nodes)

What this error means

The "no suitable node (scheduling constraints not satisfied)" error in Docker Swarm indicates that the scheduler cannot find any node in your cluster that satisfies the placement constraints you've defined for your service. Placement constraints are rules that restrict which nodes a service's tasks can run on, based on node attributes like labels, roles, or hostnames. When you deploy a service with constraints like `--constraint node.labels.region==east` or `node.role==worker`, Docker Swarm's scheduler evaluates each node against these rules. If no node matches all the specified constraints, the service tasks remain in a "Pending" state, and you see this error. Unlike placement preferences (which are best-effort hints), placement constraints are hard requirements. If the constraint cannot be satisfied, the tasks will not be scheduled at all. The scheduler will continuously try to reconcile the service's desired state, and once a suitable node becomes available (e.g., after adding the required label), the tasks will be deployed automatically.

Typical symptoms

  • Service tasks remain in 'Pending' state indefinitely
  • 'docker service ps <service>' shows task with 'no suitable node' error
  • Service replicas count stays at 0/N
  • 'docker service create' completes but service doesn't start
  • Global services don't deploy to expected nodes
  • Stack deployments partially fail with some services not starting

Common causes

  1. Node labels required by constraints don't exist on any node
  2. Typo in constraint specification (e.g., 'mode.role' instead of 'node.role')
  3. All nodes with matching labels are set to 'drain' availability
  4. Constraint uses a label key that was never added to nodes
  5. Case sensitivity mismatch between constraint and actual label value
  6. Resource reservations exceed available resources on matching nodes
  7. Host-mode port is already in use on all nodes matching constraints
  8. Architecture mismatch when using platform-specific constraints

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

1Inspect the service to see the exact constraint

First, check what constraints are defined for your service:

bash
docker service inspect <service-name> --pretty

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

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

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

2Check the current task status for detailed error

View the tasks to see the full scheduling error:

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

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

bash
docker inspect <task-id>

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

3List nodes and their labels

Check what nodes exist and their current labels:

bash
docker node ls

To see labels on all nodes:

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

For detailed labels on a specific node:

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

Compare the existing labels against what your constraint requires.

4Add the required label to a node

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

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

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

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

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

5Check node availability status

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

bash
docker node ls

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

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

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

6Fix typos in constraint syntax

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:

bash
docker service update --constraint-rm "wrong.constraint==value" \
  --constraint-add "node.labels.correct==value" <service-name>
7Verify service is running

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

bash
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.

Advanced notes

Multiple constraints: When you specify multiple constraints, ALL must be satisfied (logical AND). For example, --constraint node.role==worker --constraint node.labels.region==east requires nodes that are workers AND have the region=east label.

Constraint operators: Docker supports == (equals) and != (not equals). There's no support for other operators like >, <, or regex matching.

Global vs replicated services: Global services deploy one task per node that matches the constraints. If no nodes match, the service will have zero tasks. Replicated services will have pending tasks until suitable nodes exist.

Docker Compose deploy constraints: In a compose file, specify constraints under deploy.placement.constraints:

yaml
services:
  web:
    image: nginx
    deploy:
      placement:
        constraints:
          - node.role == worker
          - node.labels.region == east

Preferences vs constraints: If you want best-effort placement hints rather than hard requirements, use preferences instead:

bash
docker service create --placement-pref 'spread=node.labels.datacenter' nginx

Debugging tip: To see why scheduling failed on each node, you may need to check the Swarm manager logs:

bash
docker logs $(docker ps -q -f name=swarm-manager)

Resource constraints: Remember that memory/CPU reservations are also checked during scheduling. A node might match label constraints but fail due to insufficient resources. Check with docker node inspect <node> --format '{{json .Description.Resources}}'.

Built-in engine labels: In addition to custom labels, you can constrain on engine labels like node.platform.os and node.platform.arch for multi-architecture clusters.

Frequently asked questions

What does "Error response from daemon: no suitable node (scheduling constraints n" mean?
The "no suitable node (scheduling constraints not satisfied)" error in Docker Swarm indicates that the scheduler cannot find any node in your cluster that satisfies the placement constraints you've defined for your service. Placement constraints are rules that restrict which nodes a service's tasks can run on, based on node attributes like labels, roles, or hostnames. role==worker, Docker Swarm's scheduler evaluates each node against these rules.
How do I fix "Error response from daemon: no suitable node (scheduling constraints n"?
This error occurs when Docker Swarm cannot find any node in the cluster that matches the placement constraints specified for a service. The fix involves adding the required labels to nodes or adjusting your service constraints.
What causes "Error response from daemon: no suitable node (scheduling constraints n"?
Node labels required by constraints don't exist on any node Typo in constraint specification (e.g., 'mode.role' instead of 'node.role') All nodes with matching labels are set to 'drain' availability
Is the "Error response from daemon: no suitable node (scheduling constraints n" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading