docker/cli · warning

error: swarm is not locked

Error message

error: swarm is not locked

What it means

Returned by `docker swarm unlock` when the node is part of a swarm but its LocalNodeState is pending, active, or error rather than locked. Unlocking only makes sense when the manager's Raft store is encrypted-at-rest and currently locked (after a daemon restart with autolock enabled), so the CLI refuses to prompt for a key otherwise.

Source

Thrown at cli/command/swarm/unlock.go:55

}

func runUnlock(ctx context.Context, dockerCLI command.Cli) error {
	apiClient := dockerCLI.Client()

	// First see if the node is actually part of a swarm, and if it is actually locked first.
	// If it's in any other state than locked, don't ask for the key.
	res, err := apiClient.Info(ctx, client.InfoOptions{})
	if err != nil {
		return err
	}

	switch res.Info.Swarm.LocalNodeState {
	case swarm.LocalNodeStateInactive:
		return errors.New("error: this node is not part of a swarm")
	case swarm.LocalNodeStateLocked:
		break
	case swarm.LocalNodeStatePending, swarm.LocalNodeStateActive, swarm.LocalNodeStateError:
		return errors.New("error: swarm is not locked")
	}

	key, err := readKey(dockerCLI.In(), "Enter unlock key: ")
	if err != nil {
		return err
	}

	_, err = apiClient.SwarmUnlock(ctx, client.SwarmUnlockOptions{
		Key: key,
	})
	return err
}

func readKey(in *streams.In, prompt string) (string, error) {
	if in.IsTerminal() {
		fmt.Print(prompt)
		dt, err := term.ReadPassword(int(in.FD()))
		fmt.Println()

View on GitHub (pinned to e9452d6e78)

Solutions

1. Confirm state with `docker info --format '{{.Swarm.LocalNodeState}}'` — if it's `active`, no unlock is needed.
2. Enable autolock first if you expected locking: `docker swarm update --autolock=true`.
3. In restart scripts, only call unlock when the state is actually `locked`.
4. If state is `error`, inspect daemon logs to recover the swarm rather than unlocking.

Example fix

# before (script)
systemctl restart docker && docker swarm unlock < key
# after
systemctl restart docker
[ "$(docker info --format '{{.Swarm.LocalNodeState}}')" = locked ] && docker swarm unlock < key

When it happens

Trigger: Running `docker swarm unlock` when `Info.Swarm.LocalNodeState` is `active` (already unlocked or autolock disabled), `pending` (join in progress), or `error` — anything in the swarm but not `locked`.

Common situations: Running unlock twice after the first attempt succeeded; running it on a manager that was never autolocked (autolock off); scripted recovery flows that unconditionally call unlock after every daemon restart; running it on a worker node, which never locks.

Related errors

• error: this node is not part of a swarm
• cannot rotate because autolock is not turned on
• 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/2413fd6ad9aaa05d.json. Report an issue: GitHub.