docker/cli · error

unknown role {opts.role}

Error message

unknown role {opts.role}

What it means

Thrown by runJoinToken (cli/command/swarm/join_token.go:50) when the positional role argument is neither 'worker' nor 'manager'. These are the only two swarm node roles, and the CLI hard-codes an exact-string match against them.

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 4f84911bfe)

Solutions

1. Use exactly 'worker' or 'manager': `docker swarm join-token worker`.
2. Lower-case and trim the role variable before passing it; reject anything else in your wrapper.
3. Add a guard: `[ "$role" = worker ] || [ "$role" = manager ] || { echo 'bad role'; exit 1; }`.

Example fix

// before
docker swarm join-token managers

// after
docker swarm join-token manager

switch role {
case "worker", "manager":
default:
	return fmt.Errorf("invalid role %q; use worker or manager", role)
}

func isValidSwarmRole(role string) bool {
	return role == "worker" || role == "manager"
}

When it happens

Trigger: Passing any other value: `docker swarm join-token foo`, a plural like `managers`, or an empty/whitespace string from an unset variable.

Common situations: Typo; a script interpolates a role variable that is empty, mis-cased, or misspelled; assuming a default role.

Related errors

• other flags may not be combined with --rollback
• duplicate mount target
• file contents must be in PEM format
• CA cert for external CA must be in PEM format
• the external-ca option needs a protocol= parameter

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/b1a007217b08db5d. Report an issue: GitHub.