{"record":{"id":"65f8f58b7978c196","repo":"docker/cli","slug":"cannot-rotate-because-autolock-is-not-turned-on","errorCode":null,"errorMessage":"cannot rotate because autolock is not turned on","messagePattern":"cannot rotate because autolock is not turned on","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/swarm/unlock_key.go","lineNumber":55,"sourceCode":"\n\tflags := cmd.Flags()\n\tflags.BoolVar(&opts.rotate, flagRotate, false, \"Rotate unlock key\")\n\tflags.BoolVarP(&opts.quiet, flagQuiet, \"q\", false, \"Only display token\")\n\n\treturn cmd\n}\n\nfunc runUnlockKey(ctx context.Context, dockerCLI command.Cli, opts unlockKeyOptions) error {\n\tapiClient := dockerCLI.Client()\n\n\tif opts.rotate {\n\t\tres, err := apiClient.SwarmInspect(ctx, client.SwarmInspectOptions{})\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\n\t\tif !res.Swarm.Spec.EncryptionConfig.AutoLockManagers {\n\t\t\treturn errors.New(\"cannot rotate because autolock is not turned on\")\n\t\t}\n\n\t\t_, err = apiClient.SwarmUpdate(ctx, client.SwarmUpdateOptions{\n\t\t\tVersion: res.Swarm.Version,\n\t\t\tSpec:    res.Swarm.Spec,\n\n\t\t\tRotateManagerUnlockKey: true,\n\t\t})\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\n\t\tif !opts.quiet {\n\t\t\t_, _ = fmt.Fprintln(dockerCLI.Out(), \"Successfully rotated manager unlock key.\")\n\t\t}\n\t}\n\n\tresp, err := apiClient.SwarmGetUnlockKey(ctx)","sourceCodeStart":37,"sourceCodeEnd":73,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/swarm/unlock_key.go#L37-L73","documentation":"Thrown by runUnlockKey (cli/command/swarm/unlock_key.go:55) when `--rotate` is requested but the swarm's EncryptionConfig.AutoLockManagers is false. Rotating the unlock key only makes sense when autolock is on (the key encrypts Raft logs at rest); without autolock there is no key material role to rotate.","triggerScenarios":"Running `docker swarm unlock-key --rotate` on a swarm where autolock was never enabled (`docker swarm update --autolock` was not run).","commonSituations":"Operator wants to rotate keys but never turned on autolock; assuming autolock is the default (it is off by default).","solutions":["Enable autolock first: `docker swarm update --autolock`.","Capture the resulting key immediately (`docker swarm unlock-key`) and store it safely.","Then rotate: `docker swarm unlock-key --rotate`."],"exampleFix":"// before\ndocker swarm unlock-key --rotate   # autolock off -> error\n\n// after\ndocker swarm update --autolock\ndocker swarm unlock-key            # capture & store the key\ndocker swarm unlock-key --rotate   # now valid","handlingStrategy":"validation","validationCode":"res, err := apiClient.SwarmInspect(ctx, client.SwarmInspectOptions{})\nif err != nil { return err }\nif !res.Swarm.Spec.EncryptionConfig.AutoLockManagers {\n\treturn errors.New(\"autolock is off; enable before rotating the unlock key\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Enable autolock as part of swarm provisioning, not at rotation time.","Store unlock keys in a password manager immediately after enabling.","Gate `--rotate` behind an autolock status check."],"tags":["docker","swarm","unlock-key","autolock","rotation"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}