docker/cli · error

no unlock key is set

Error message

no unlock key is set

What it means

Raised by `docker swarm unlock-key` when the Swarm API's SwarmGetUnlockKey call succeeds but returns an empty key. The CLI treats an empty key as "autolock is not enabled on this swarm," because a non-empty unlock key only exists when manager autolock is turned on.

Source

Thrown at cli/command/swarm/unlock_key.go:79

			RotateManagerUnlockKey: true,
		})
		if err != nil {
			return err
		}

		if !opts.quiet {
			_, _ = fmt.Fprintln(dockerCLI.Out(), "Successfully rotated manager unlock key.")
		}
	}

	resp, err := apiClient.SwarmGetUnlockKey(ctx)
	if err != nil {
		return fmt.Errorf("could not fetch unlock key: %w", err)
	}

	if resp.Key == "" {
		return errors.New("no unlock key is set")
	}

	if opts.quiet {
		_, _ = fmt.Fprintln(dockerCLI.Out(), resp.Key)
		return nil
	}

	printUnlockCommand(dockerCLI.Out(), resp.Key)
	return nil
}

func printUnlockCommand(out io.Writer, unlockKey string) {
	if len(unlockKey) > 0 {
		_, _ = fmt.Fprintf(out, "To unlock a swarm manager after it restarts, "+
			"run the `docker swarm unlock`\ncommand and provide the following key:\n\n    %s\n\n"+
			"Remember to store this key in a password manager, since without it you\n"+
			"will not be able to restart the manager.\n", unlockKey)
	}

View on GitHub (pinned to e9452d6e78)

Solutions

1. Enable autolock first: `docker swarm update --autolock=true`, which prints and sets an unlock key.
2. Alternatively run `docker swarm unlock-key --rotate` after enabling autolock to generate a fresh key.
3. Verify you are targeting the intended swarm manager (`docker context ls`, `docker info | grep -i autolock`).

Example fix

# before
docker swarm unlock-key
# Error: no unlock key is set

# after
docker swarm update --autolock=true
docker swarm unlock-key -q

When it happens

Trigger: Running `docker swarm unlock-key` (with or without --quiet) against a swarm where autolock is disabled; apiClient.SwarmGetUnlockKey returns resp.Key == "" in cli/command/swarm/unlock_key.go:79.

Common situations: Users run `docker swarm unlock-key` on a fresh swarm assuming a key exists by default; scripts that fetch the unlock key before autolock was ever enabled; running against the wrong context/host that points at a non-autolocked swarm.

Related errors

• conflicting options: cannot specify both --host and --contex
• user agent cannot be blank
• docker endpoint configuration is required
• no context specified
• unrecognized config key:

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