docker/cli · error

error: this node is not part of a swarm

Error message

error: this node is not part of a swarm

What it means

Returned by `docker swarm unlock` when the daemon's Info reports LocalNodeState == inactive, meaning this node has never joined (or has left) a swarm. The CLI checks node state before prompting for an unlock key, so it fails fast instead of asking for a key that can't be used.

Source

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

		DisableFlagsInUseLine: true,
	}

	return cmd
}

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) {

View on GitHub (pinned to e9452d6e78)

Solutions

1. Check where your CLI points (`docker context show`, `DOCKER_HOST`) and run the command on an actual swarm manager.
2. Verify node state with `docker info --format '{{.Swarm.LocalNodeState}}'`.
3. If the node should be in the swarm, rejoin it with `docker swarm join` (unlock only applies to already-joined locked managers).
4. If you meant to create a swarm, run `docker swarm init` instead.

When it happens

Trigger: Running `docker swarm unlock` on a host where `Info.Swarm.LocalNodeState` is `inactive` — the node is not part of any swarm. Only the Info API call is made; SwarmUnlock is never attempted.

Common situations: Running unlock on the wrong host (a worker that left, or a fresh machine); DOCKER_HOST/context pointing at a non-swarm daemon; the node was removed from the swarm or `docker swarm leave` was run; confusion after a daemon reinstall wiped swarm state.

Related errors

• error: swarm is not locked
• 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/58c9687175ba0da1.json. Report an issue: GitHub.