docker/cli · info · errNoRoleChange

role was already set to the requested value

Error message

role was already set to the requested value

What it means

errNoRoleChange is returned by `docker node promote`/`docker node demote` when the node already has the requested role. The promote/demote helpers detect the no-op before submitting a NodeUpdate and report it; the callers typically treat it as informational ('node is already a manager/worker') rather than a hard failure.

Source

Thrown at cli/command/node/update.go:22

package node

import (
	"context"
	"errors"
	"fmt"
	"maps"

	"github.com/docker/cli/cli"
	"github.com/docker/cli/cli/command"
	"github.com/docker/cli/cli/command/completion"
	"github.com/docker/cli/opts"
	"github.com/moby/moby/api/types/swarm"
	"github.com/moby/moby/client"
	"github.com/spf13/cobra"
	"github.com/spf13/pflag"
)

var errNoRoleChange = errors.New("role was already set to the requested value")

func newUpdateCommand(dockerCLI command.Cli) *cobra.Command {
	options := newNodeOptions()

	cmd := &cobra.Command{
		Use:   "update [OPTIONS] NODE",
		Short: "Update a node",
		Args:  cli.ExactArgs(1),
		RunE: func(cmd *cobra.Command, args []string) error {
			return runUpdate(cmd.Context(), dockerCLI, cmd.Flags(), args[0])
		},
		ValidArgsFunction:     completeNodeNames(dockerCLI),
		DisableFlagsInUseLine: true,
	}

	flags := cmd.Flags()
	flags.StringVar(&options.role, flagRole, "", `Role of the node ("worker", "manager")`)
	flags.StringVar(&options.availability, flagAvailability, "", `Availability of the node ("active", "pause", "drain")`)

View on GitHub (pinned to e9452d6e78)

Solutions

1. Treat it as a no-op success — the node is already in the desired role; check with `docker node ls` first
2. Make automation idempotent by checking `docker node inspect --format '{{.Spec.Role}}'` before promoting/demoting
3. Verify you targeted the intended node if the role was expected to differ

When it happens

Trigger: `docker node promote <node>` on a node whose role is already manager, or `docker node demote <node>` on one already a worker; with multiple nodes, any node already in the target role triggers it for that node.

Common situations: Idempotent provisioning scripts (Ansible/cloud-init) that promote nodes on every run; retrying a promote after a partially observed failure; operating on the wrong node name.

Related errors

• node ID not found in /info
• cannot supply extra formatting options to the pretty templat
• replicas can only be used with replicated or replicated-job
• replicas-max-per-node can only be used with replicated or re
• max-concurrent can only be used with replicated-job mode

AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01). Data as JSON: /data/errors/590271a1ca922faf.json. Report an issue: GitHub.