Bring a Locked Swarm Manager Back After Restart
A Docker Swarm manager with autolock on comes back from a restart refusing to do anything until you feed it the right key. This guide gets it usable again and confirms the daemon actually works. The installed command is Docker Community Edition CLI 29.8.1 from package docker-ce-cli version 5:29.8.1-1~ubuntu.24.04~noble. Allow about five minutes if you already have the current key. You need a shell on the affected manager and, normally, Docker access through your current user. It changes the manager's locked state, so run it during an approved recovery window.
The route
Jump straight to the step you need, or tick off Done means at the end.
1. Confirm that this is an unlock problem
Do not start by guessing a key. First check the daemon's response with a read-only command:
$ docker service ls
Error response from daemon: Swarm is encrypted and needs to be unlocked before it can be used. Use "docker swarm unlock" to unlock it.The exact wording can vary with the daemon version, but the diagnosis is the same: the swarm is encrypted and locked. This normally follows a restart when autolock is enabled. A worker joining a swarm is a different case entirely; this procedure is for a locked manager only.
Checkpoint
If docker service ls lists services, the manager is already usable and there is nothing to do here. If Docker instead reports that this node is not part of a swarm, stop and investigate membership instead: a key cannot repair a node with no swarm state.
2. Find the recorded key
- Use the key from setup or the last rotation. It usually begins with
SWMKEY-1-. Retrieve it from the approved password manager or other protected operational record. - Treat it as a credential. It secures the manager's encrypted TLS and Raft data, so it never belongs in a ticket, shell history, chat message or public script.
- No local command reconstructs it. A locked manager cannot regenerate its own key.
If another manager is healthy and the key has not been rotated since this node went down, an operator may be able to display the current key there:
$ docker swarm unlock-key
To unlock a swarm manager after it restarts, run the `docker swarm unlock` command and provide the following key:
SWMKEY-1-REPLACE_WITH_THE_KEY_SHOWN_BY_DOCKERThat output is sensitive: do not copy the placeholder above, and do not paste a real key into a transcript. If the key was rotated after this manager went offline, the current key may not fit its older state, so keep the old key record on hand during the rotation window.
3. Unlock the manager interactively
Run this on the locked manager itself:
$ docker swarm unlock
Please enter unlock key:Paste the real key only at the prompt, then press Enter. This installed command does not take the key as a command-line option, which conveniently keeps it out of the process list. Success returns you to the shell; no service restart needed.
Elevated privileges are not automatic here. Use sudo docker swarm unlock only if your Docker socket permissions require it and running Docker through sudo is already normal for this host. Never put the key directly in a command line such as docker swarm unlock SWMKEY-...: the command has no such argument, and a credential typed into a shell can be picked up by monitoring tools.
Checkpoint
A wrong key should fail cleanly rather than half-unlock the manager. Treat repeated failures as a reason to stop and check the manager, the key source and whether a rotation happened, not as a cue to try random values.
4. Verify recovery
Run a harmless query immediately after the prompt returns:
$ docker service ls
ID NAME MODE REPLICAS IMAGEThe table will hold your own services, so the identifiers and replica counts will differ; an empty table can still be a successful query if this swarm runs no services. As a second check, look at the node view:
$ docker node ls
ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS ENGINE VERSION
REPLACE_WITH_NODE_ID REPLACE_HOST Ready Active Leader 29.8.1Use the real output, not the placeholders, to judge health. A manager can be freed from its lock and still have a separate quorum, network or service problem. Check the Docker daemon logs through your host's normal service tooling if these queries fail for another reason.
5. Recover when the key is unavailable
Warning
Do not turn autolock off just because the key is inconvenient. That changes the at-rest protection for the swarm's TLS and Raft encryption keys, which is a security decision in its own right, and it still will not open a manager whose encrypted state you cannot access.
If the current key is rejected, compare the recorded rotation time against the manager outage. Ask the swarm operator whether an older key applies and whether another manager still holds quorum. If nothing usable turns up, Docker's documented recovery path may mean forcing this manager to leave and rejoining it as a new manager, which is disruptive and can wipe local manager state. Do not run a forced leave or rejoin off the back of this guide alone: get a recovery plan, a quorum check and the correct join procedure first.
If the node is not actually a swarm member, that is a separate membership problem. If the daemon is stopped, start it through the host's approved service manager before retrying the read-only diagnosis. Neither is fixed by finding more keys.
Done means
- Problem confirmed. The affected node was confirmed as a locked Swarm manager, not a membership or daemon issue.
- Key sourced safely. It came from an approved protected record or a healthy manager, never a guess.
- Unlocked cleanly.
docker swarm unlockran interactively, with the key never exposed in the command line or logs. - Service confirmed.
docker service lscompleted successfully after unlocking. - Bigger decisions deferred. Any key rotation, forced leave, rejoin or autolock change was left for a separately approved recovery decision.