docker/cli · error

unknown role %s

Error message

unknown role %s

What it means

Returned by `docker swarm join-token` when the positional ROLE argument is neither "worker" nor "manager". The command only knows how to fetch or rotate join tokens for these two swarm roles, so any other value is rejected before any API call is made.

Source

Thrown at cli/command/swarm/join_token.go:50

			"version": "1.24",
			"swarm":   "manager",
		},
		DisableFlagsInUseLine: true,
	}

	flags := cmd.Flags()
	flags.BoolVar(&opts.rotate, flagRotate, false, "Rotate join token")
	flags.BoolVarP(&opts.quiet, flagQuiet, "q", false, "Only display token")

	return cmd
}

func runJoinToken(ctx context.Context, dockerCLI command.Cli, opts joinTokenOptions) error {
	worker := opts.role == "worker"
	manager := opts.role == "manager"

	if !worker && !manager {
		return errors.New("unknown role " + opts.role)
	}

	apiClient := dockerCLI.Client()

	if opts.rotate {
		res, err := apiClient.SwarmInspect(ctx, client.SwarmInspectOptions{})
		if err != nil {
			return err
		}

		_, err = apiClient.SwarmUpdate(ctx, client.SwarmUpdateOptions{
			Version:            res.Swarm.Version,
			Spec:               res.Swarm.Spec,
			RotateWorkerToken:  worker,
			RotateManagerToken: manager,
		})
		if err != nil {
			return err

View on GitHub (pinned to e9452d6e78)

Solutions

1. Use exactly `docker swarm join-token worker` or `docker swarm join-token manager` (lowercase).
2. In scripts, validate the role variable against the two allowed values before calling the CLI.
3. Add `-q` if you only need the token string, and `--rotate` to invalidate the old token.

Example fix

# before
docker swarm join-token Master
# after
docker swarm join-token manager

When it happens

Trigger: Invoking `docker swarm join-token <role>` with a role other than the exact lowercase strings "worker" or "manager" — e.g. `docker swarm join-token node`, `docker swarm join-token Manager`, a typo like `worekr`, or an empty/scripted variable that expanded to something else.

Common situations: Shell scripts interpolating an unset or misspelled variable for the role; users guessing role names like "leader", "master", or "node"; capitalization mistakes since the comparison is case-sensitive.

Related errors

• the external-ca option needs a protocol= parameter
• the external-ca option needs a url= parameter
• node ID not found in /info
• cannot supply extra formatting options to the pretty templat
• role was already set to the requested value

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