diff --git a/doc/rocks.txt b/doc/rocks.txt
index 4d674d74..37759db3 100644
--- a/doc/rocks.txt
+++ b/doc/rocks.txt
@@ -71,6 +71,12 @@ RocksOpts                                                            *RocksOpts*
         {luarocks_config?}                (string)   Path to the luarocks config. If not set, rocks.nvim will create one in `rocks_path`. Warning: You should include the settings in the default luarocks-config.lua before overriding this.
 
 
+                                                         *rocks.troubleshooting*
+
+What to do when an installation fails ?
+1. fall back to https://github.com/nvim-neorocks/rocks-git.nvim (cons: doesn't list dependencies)
+2. Add the plugin to luarocks.org <link on guide how to do that?
+
 ==============================================================================
 Lua API for rocks.nvim extensions                                    *rocks.api*
 
diff --git a/lua/rocks/config/init.lua b/lua/rocks/config/init.lua
index ee7c7359..a4a95e41 100644
--- a/lua/rocks/config/init.lua
+++ b/lua/rocks/config/init.lua
@@ -27,4 +27,11 @@ local config = {}
 ---@type RocksOpts | fun():RocksOpts
 vim.g.rocks_nvim = vim.g.rocks_nvim
 
+---@tag rocks.troubleshooting
+---@brief [[
+---
+---What to do when an installation fails ?
+---1. fall back to https://github.com/nvim-neorocks/rocks-git.nvim (cons: doesn't list dependencies)
+---2. Add the plugin to luarocks.org <link on guide how to do that?
+---@brief ]]
 return config
diff --git a/lua/rocks/operations/init.lua b/lua/rocks/operations/init.lua
index c38ccb92..0b5f37f5 100644
--- a/lua/rocks/operations/init.lua
+++ b/lua/rocks/operations/init.lua
@@ -542,7 +542,9 @@ operations.add = function(arg_list, callback)
                 local stderr = installed_rock
                 ---@cast stderr string
                 local not_found = stderr:match("No results matching query were found") ~= nil
-                local message = ("Installation of %s failed. Run ':Rocks log' for details."):format(rock_name)
+                local message = ("Installation of %s failed. Run ':Rocks log' for details and :h rocks.troubleshooting"):format(
+                    rock_name
+                )
                 if not_found then
                     message = ("Could not find %s %s"):format(rock_name, version or "")
                 end